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Welcome + 

1 


his manual is about object-oriented programming in THINK Pascal. It de¬ 
scribes the object extensions to Pascal and the THINK Class Library. The 
THINK Class Library is a collection of classes that define a generic Macintosh 
application. 

If you're new to object-oriented programming 

You should read this chapter and Chapter 3, “Object-Oriented Program¬ 
ming.” Then read the first part of Chapter 4, “Object Pascal,” and follow the 
tutorial in Chapter 5, “Tutorial: LearnOOP.” 

If you're familiar with object-oriented programming 

Read this chapter, Chapter 4, “Object Pascal,” and Chapter 7, “The THINK 
Class Library.” 

If you know the THINK Class Library 

Be sure to read “What’s New in the THINK Class Library” on page 6 in this 
chapter. Then read Chapter 4, “Object Pascal to learn about the object exten¬ 
sions to THINK Pascal. You should scan though Chapter 7, “The THINK 
Class Library,” and read Chapter 8, “Exception Handling.” 
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What's in this Manual 

This manual is organized in four sections: Getting Started, Object-Oriented 

Programming in THINK Pascal, The THINK Class Library, and Appendix. 

Getting Started 

This is the section you’re reading. It contains this chapter and instructions for 

installing the THINK Class Library. 

Object-Oriented Programming 

This section describes object-oriented programming with THINK Pascal. 

Object-Oriented Programming This chapter is a general introduc¬ 
tion to object-oriented program¬ 
ming. You’ll learn the 
terminology and basic concepts 
of object-oriented programming. 

Object Pascal This chapter describes Object 

Pascal, the object extensions to 
THINK Pascal. 

Tutorial: LearnOOP LearnOOP is a hands-on demon¬ 

stration of the basic concepts of 
object-oriented programming. 

The Class Browser This chapter shows you how to 

use the THINK Pascal Class 
Browser. The browser is a tool 
that lets you examine your classes 
and look up definitions of in¬ 
stance variables and methods. 


The THINK Class library 

This section contains 66 chapters that describe the THINK Class Library and 
each class in the library. This section is designed for both THINK C and 
THINK Pascal programmers. 

The THINK Class Library This chapter introduces you to 

the class library. It gives you an 
overview, and tells you how the 
different parts of the THINK Class 
Library fit together. Be sure to 
read this chapter even if you’ve 
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Exception Handling 


Chapter 9-Chapter 70 


TCL Library Routines 


Global Variables 


used the THINK Class Library be¬ 
fore. 

This chapter describes the excep¬ 
tion handling mechanism used in 
the THINK Class Library. The ex¬ 
ception handling mechanism lets 
you handle errors in a consistent 
and graceful way. 

These chapters describe each 
class in the THINK Class Library. 

This chapter describes library 
routines used throughout the 
THINK Class Library. 

This chapter lists all of the global 
variables that the THINK Class Li¬ 
brary uses. 


Appendix 

This is the section contains an appendix about using THINK Pascal with 
MacApp 2.0. 

What's New in the THINK Class Library 

This version of the THINK Class Library is version 1.1. If you’ve used earlier 
versions of the THINK Class Library, you’ll find that the fundamental model 
behind the TCL has not changed. The visual hierarchy and the chain of com¬ 
mand work just as they did before. This section describes the most important 
new features of this version of the THINK Class Library and how they affect 
your existing programs. 

Long coordinates 

The visual hierarchy now uses 32-bit (long) coordinates. This change means 
that your panes and panoramas are no longer limited to the QuickDraw co¬ 
ordinate space. You don’t have to use 32-bit coordinates. In fact, the default 
is to make turn long coordinates off. However, this change will require you 
to modify your programs. 
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The THINK Class Library uses the types LongRect and LongPt throughout 
the CView family. These types are defined like this in C: 

typedef struct LongPt 

{ 

long v, h; 

} LongPt; 

typedef struct LongRect 

{ 

long top, left, bottom, right; 

} LongRect; 

And like this in Pascal: 
type 

LongPt = record 

case integer of 
1: ( v, h: longint 

) ; 

2: ( vh: array[VHSelect] of longint 

) ; 

end; 

LongRect = record 

case integer of 
1: ( top, left, 

bottom, right: longint 

) ; 

2: ( topLeft: LongPt; 

botRight: LongPt 

); 

end; 

Please be sure to read “Working with Panes” on page 77 and the description 
of CPane. To help make the transition easier, you should also read “Long Co¬ 
ordinate Utilities” on page 462. 

Improved error handling 

The TCL now uses an exception handling mechanism to catch errors. This 
mechanism lets you separate the normal flow of your code from the error 
handling code. Most of the classes in the THINK Class Library use the excep¬ 
tion handling mechanism. Be sure to read Chapter 8, “Exception Handling.” 
For a good example of exception handling, look at the CDataFile class. 

Dependent objects 

All of the chain of command classes are now descendants of a new class 
called CCollaborator. This class lets you set up dependencies between ob- 
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jects, so one object can announce a change to its dependents. Read the 
chapter on CCollaborator. 

Director owners 

In earlier versions of the THINK Class Library, only an application could a di¬ 
rector’s supervisor. This version introduces a new class, CDirectorOwner, for 
objects that own directors. CApplication and CDirector are director owners. 
This class lets you create multi-window documents by creating directors that 
are supervised by other directors or documents. 

Abstract text 

The class CAbstractText defines characteristics of text classes. The class 
CStaticText has been removed. Instead, you specify whether text is editable, 
styleable, or selectable. See the chapters on CEditText and CAbstractText. 

Compatibility with earlier versions 

Older versions of the classes that have changed substantially in this version 
of the THINK Class Library are in the Compatibility classes folder. 


Old Class 

CBaiOwner 

Replaced because... 

The functionality that CBaiOwner provid¬ 
ed is now part of CBartender. 

CBorder 

Borders are now handled by CPaneBorder 
which is not a subclass of CPane. 

CColorWindow 

This functionality is no w in CWindow. 

CRadioButton 

CRadioGroup 

The new class CRadioGroupPane is a 
pane that groups radio controls. CRadio- 
Control replaces CRadioButton. 

CStaticText 

All text classes are now descendants of 
CAbstractText. For static text, use CEdit¬ 
Text, but specify that it is not editable. 

CCluster 

CList 

These classes are now descendants of 

CArray. The old classes are named OClus- 
ter and OList. 

CFile 

CDataFile 

These classes now use the exception han¬ 
dling mechanism instead of returning er¬ 
ror codes. The old classes are named 

OFile and ODataFile. 
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his chapter tells you how to install the THINK Class Library on your disk. 
The THINK Class Library is a set of classes that implement a generic Macin¬ 
tosh application. Chapter 7, “The THINK Class Library,” talks about the 
THINK Class Library in detail. 


You don’t need to use the THINK Class Library to use Object Pascal. If you 
just want to learn how to useobject-oriented programming with THINK Pas¬ 
cal, read Chapter 3, “Object-Oriented Programming,” and Chapter 4, “Object 
Pascal.” 


Contents 

Installation .... .11 

Building the Starter Project. .12 

Installing the TMPL Resources into ResEdit. .13 
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Installation 

Before you install the THINK Class Library on your disk, be sure that you fol¬ 
lowed the instructions in THINK Pascal User Manual, Chapter 2, “Installing 
THINK Pascal.” Also, make sure you have enough space on your hard disk. 
The files that make up the core of the THINK Class Library take up nearly 
1300K of disk space. 


Note 

You’ll want to install the THINK Class Library demos even if 
you’re familiar with the previous version of the THINK 
Class Library. The demos show you how to use new classes 
and take advantage of changes in old classes. 


To install the THINK Class Library, run the self-extracting archive THINK 
Class Library 1.1. sea, and choose your Development folder as the 
destination folder. This archive creates a folder called THINK Class 
Library 1.1 and puts these files and folders in it: 


This file or folder... 

Core classes 

TCL Libraries 
Control classes 

Dialog classes 
File classes 

FW/Tearoffs 

Table classes 

Text classes 

More classes 

Compatibility classes 


Contains... 

The basic classes all applications 
need. 

Utility routines. 

Classes for buttons and pop-up 
menus. 

Classes for dialogs. 

Classes for specific kinds of files. 
CFile is in Core classes. 
Classes for floating windows and 
tear-off menus. 

Classes for tables, like spread¬ 
sheets and lists. 

Classes for editing and displaying 
text. 

Classes that don’t fall into any of 
the above categories, like CBit- 
Map, CStack and CTextEnvirons. 
Classes from THINK Class Library 
1.0 that have been replaced with 
new classes. 
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This file or folder... 

TCL 1.1 doc 


TCL Resources 
TCL TMPLs 


Contains... 

Documentation on some parts of 
the THINK Class Library, includ¬ 
ing classes for dialogs and tables. 
The standard resources you need 
to use the THINK Class Library. 

A set of TMPL resources that 
make it easy to create resources 
for pane initialization. The next 
set of instructions tell you how to 
install these TMPLs into ResEdit. 


To install the demos for the THINK Class Library, run the self-extracting ar¬ 
chive TCL 1.1 Pascal Demos . sea, and choose your Development 
folder as the destination folder. This archive creates a folder called TCL 
1.1 Pascal Demos and puts folders in it: 


This demo in this folder... 

Art Class Demo 

NewClassDemo Folder 

Starter Folder 

TinyEdit Folder 


Is... 

A drawing program that uses tear- 
off menus and floating windows. 
A demonstration of some of the 
THINK Class Library’s new fea¬ 
tures, including classes for dia¬ 
logs, tables, pop-up menus, and 
styled text editing 
A minimal project that you can 
use as a starting point for your 
own project. It just open and clos¬ 
es empty windows. 

A small text editor based on the 
Starter project. 


Building the Starter Project 

You’ll use the Starter .n and Starter .Build. K projects as the basis for 
all your THINK Class Library-based applications. If you build this project 
now you’ll save a lot of time later since THINK Pascal will only need to 
recompile the new files that you add to the project. 


THINK Pascal stores the compiled code for all your source files in the project 
document, so when you duplicate the Starter Folder to create your 
own projects, the THINK Class Library files will be already compiled. Since 
building can take anywhere from five minutes on a Macintosh Ilci to over 
half an hour on a Macintosh Plus, you can save yourself a lot of time later by 
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spending a few minutes building the projects now. The built projects require 
about 850K of disk space. 

To build the Starter .n and Starter .Build, n projects, follow these 
steps: 

1. Open the project Starter .n, in the Starter Folder. 

2. Choose the Build command from the Run menu. THINK Pascal 
loads all the libraries and compiles all the source files. 

3. Choose Close Project from the Project menu. 

4. Choose Open Project from the Project menu and open the 
project Starter .BuiId. n. 

5. Choose the Build command from the Run menu. 

6. Choose Quit from the File menu to return to the Finder. 

THINK Pascal uses two projects—one for debugging and one for building 
the final application. When you build an application, THINK Pascal has to 
turn the debugging options off. That means that the entire THINK Class Li¬ 
brary would need to be recompiled. By using two projects and switching to 
the . Build . n project when you want to build the final application, only 
your own files will need to be recompiled. 

Installing the TMPL Resources into ResEdit 

If you use ResEdit to create and edit your resource files, you should install 
the TMPL resources from TCL TMPLs into your copy of ResEdit. The TMPL 
resources are resource editor templates for ResEdit. After you install them, it 
will be easy for you to create certain THINK Class Library resources with 
ResEdit. Follow these steps to install the TMPL resources into ResEdit. 

1. Make a duplicate copy of ResEdit. 

2. Double-click on the duplicate copy of ResEdit you just made. 

3. Open the file TCL TMPLs. 

4. Select the item TMPL. 

5. Choose Copy from the Edit menu. 

6. Open the original copy of ResEdit. 

7. Choose Paste from the Edit menu. 

8. Choose Quit from the File menu. When ResEdit asks you to con¬ 
firm the changes, click on the Yes button. 

9. Delete your copied version of ResEdit. 

ResEdit is included in your THINK Pascal package in the Resource 
Utilitiles . sea archive. To install it, follow the instructions in the 
THINK Pascal User Manual, Chapter 2, “Installing THINK Pascal.” 
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bject-oriented programming is not hard to learn. In fact, the hardest thing 
about object-oriented programming is unlearning what you already know 
about procedural (traditional) programming. To make object-oriented pro¬ 
gramming easier to learn, this chapter uses examples and comparisons to 
procedural programming. The examples should make some concepts more 
concrete, and the comparisons to procedural programming will help you re¬ 
late what you’re learning to something you already know. 


Contents 

Overview. . . 19 

Objects and Messages. . 19 

Classes. .20 

Inheritance and Polymorphism .21 

Objects and the Macintosh Interface . .22 

Working with Objects. .23 

What classes should I define?. .23 

When should I create a subclass? .... .23 

What should be a method?. .24 

When should I use procedural programming? . 24 

Where to Go Next . . 24 
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Overview 

The basic difference between procedural and object-oriented programming 
is in the way the two disciplines treat data and action. In procedural pro¬ 
gramming, data and action are two separate things. You define your data 
structures, and then you define some routines to operate on them. For each 
data structure you define, you need a new set of routines. 

In object-oriented programming, action and data are closely coupled. When 
you define your data— your objects— you also define their actions. Instead 
of a set of routines that do something to data, you have a set of objects inter¬ 
acting with each other. 

Objects and Messages 

An object is an entity that contains some data and an associated set of ac¬ 
tions that operate on the data. To make an object perform one of its actions, 
you send it a message. 

For example, you might create an object that represents a rectangle. Its data 
contains the locations of the rectangle’s four corner points, and its actions 
might include drawing, erasing, and moving. To draw a rectangle, you send 
the rectangle a draw message. 


Note 

For the time being, don’t worry about how to send a mes¬ 
sage to an object. The important thing is to start thinking of 
sending messages as requesting an object to do something. 


Contrast this with the way you’d do the same thing in procedural program¬ 
ming. First you define a record that represents the four corners of the data 
structures, and then you define three routines to draw, to erase, and to move 
a rectangle. Each of the routines would take a rectangle data structure as an 
argument. 

So the first big advantage of object-oriented programming over procedural 
programming is that you can keep the routines that operate on a data struc¬ 
ture together with the data structure they’re operating on. This “keeping to¬ 
gether” is called encapsulation. 
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Classes 

Encapsulation is a minor advantage of object-oriented programming. A more 
significant advantage is that objects can inherit data and behavior from other 
objects. 

Every object belongs to a class, which defines the implementation of a par¬ 
ticular kind of object. A class describes the object’s data and the messages it 
responds to. 

Classes are very much like record declarations. You define the private data 
for the class the same way as you would the fields of a record. In classes, 
though, the fields are called Instance variables. Each instance of a class, 
each object, has its own instance variables just as each variable of a record 
type has the same fields. 

When you send an object a message, it invokes a routine that implements 
that message. These routines are called methods. The class definition in¬ 
cludes the method implementations. 

One important thing to keep in mind is that message and method are not the 
same thing. A message is what you send to an object. How an object re¬ 
sponds to a message is the method. 

You can think of a class as a template for creating objects. It describes an ob¬ 
ject’s data and the messages it responds to. An object is called an instance 
of a class. You can also say that an object is a member of a class. 

The rest of this chapter uses pictures like this to represent classes. This is 
what the rectangle class in the example above looks like: 

Class 

Rectangle 

Instance variables 

top 
left 

bottom 
right 

Messages 
Draw 
Erase 
Move 


Methods 

draw line from point to point 
erase lines 
offset points 
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Inheritance and Polymorphism 

You can define a class in terms of an existing class. The new class is called 
the subclass, and the existing class is called the superclass. A class without 
a superclass is said to be a root class. A subclass inherits all the instance 
variables and methods of its superclass. Subclasses can define additional in¬ 
stance variables and methods. Subclasses can also override methods de¬ 
fined by the superclass. 

Overriding a method means that the subclass responds to the same message 
as its superclass, but it uses its own method to respond to the message. 

For example, suppose you want to create a class to represent employees. 
Two of the instance variables might be the person’s name and birth date. 
You might define three methods, GetName, GetAge and GetWkPay, to re¬ 
turn the person’s name, to calculate the person’s age from the birth date, and 
to return the person’s weekly salary. 

Class 

Employee 

Superclass 

none 

Instance variables 

Name 

Birthdate 

Messages Methods 

GetName return Name 

GetAge return (Today - Birthdate) 

GetWkPay return 0 

Now you can use the Employee class to create two new subclasses: Hourly- 
Employee and ExemptEmployee. Both of these classes inherit all the in¬ 
stance variables from the Employee class. Each class, however, defines a 
new instance variable to store the salary, and each class overrides the 
GetWkPay method to return the appropriate weekly salary. 

This is what the HourlyEmployee class looks like. 

Class 

HourlyEmployee 
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Superclass 

Employee 

Instance variables 

HourlySalary 

Messages Methods 

GetWkPay return (HourlySalary * 40) 

And this is what the ExemptEmployee class looks like. 

Class 

ExemptEmployee 

Superclass 

Employee 

Instance variables 

YearlySalary 

Messages Methods 

GetWkPay return (YearlySalary / 52) 

As long as your object is a member of any of the Employee classes, you can 
send it GetName, GetAge, and GetWkPay messages, and the object will re¬ 
spond properly. 

This ability to send the same message to objects of different classes is called 
polymorphism. If you need to create a new kind of employee (a salesper¬ 
son on commission), all you need to do is define a subclass of Employee 
and override the GetWkPay method. Any routine that sends GetWkPay mes¬ 
sages to employee objects would still work. 

Consider for a moment how you would do the same thing in procedural pro¬ 
gramming. Your employee record would need a flag field to specify whether 
it was an HourlyEmployee or an exempt employee. Then, your GetWkPay 
function would check this field and calculate the weekly salary appropriate¬ 
ly. If you added a salesperson, you would have to change the GetWkPay 
function to handle the salary calculation for the new kind of employee. 

Objects and the Macintosh Interface 

The Macintosh interface lends itself to object-oriented programming. For in¬ 
stance, in the Finder, the effect of the Open command depends on the icons 
you’ve selected. If you select a folder, it opens the folder. If you select an ap- 


22 Object-Oriented Programming 


Working with Objects 


♦ 


plication it launches the application. If you select a document, it launches 
the application and tells it to open the selected document. What you’re do¬ 
ing is sending an Open message to different Finder objects. Each object uses 
its own Open method to carry out the request. 

Think of the visual entities on the Macintosh screen—windows, controls, the 
menu bar, icons—as objects. They’re things that are waiting to do some¬ 
thing. Think of your actions—clicking, dragging, typing—as messages. 
You’re sending messages to the Macintosh objects. 

The THINK Class Library, included with your THINK Pascal package, pro¬ 
vides a set of classes that let you work with these Macintosh elements from 
an object-oriented point of view. You can read more about the THINK Class 
Library in Chapter 7, “The THINK Class Library.” 

Working with Objects 

If you’ve never worked with object-oriented programming, this section will 
give you some general guidelines for designing classes. As you get more 
comfortable with object-oriented programming, you’ll build up a collection 
of classes you can use in any of your applications. If you want to see how 
extensive a library of classes can be, look at the THINK Class Library. 

What classes should I define? 

Usually, you define only one root-level class and then define all the other 
classes as descendants of that class. The advantage of this approach is that 
you can define behavior that applies to all the objects in your application. 

This root-level class is an example of an abstract class. You don’t create in¬ 
stances of abstract classes. Instead, you use them to give a family of objects 
common behavior. The Employee class in the example above is an abstract 
class. Its function is to provide the common instance variables and methods 
you’ll need for all employees. 

In general, you should define a class (or a subclass of your root class) for 
each concept your application deals with. 

When should I create a subclass? 

Create a subclass whenever you need to change the behavior of a method or 
when you need to add more instance variables. If you write a method that 
does different things depending on the value of some instance variable, it’s 
probably time to create a subclass. 
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What should be a method? 

Typically, any action an object can make should be a method. It’s consid¬ 
ered good practice to provide methods to set and get the values of instance 
variables rather than allowing other functions to access them directly. If you 
find yourself passing an object as a parameter to a function to manipulate its 
instance variables, you should turn the function into a method. 

When should I use procedural programming? 

Object-oriented programming isn’t the answer to all programming problems. 
Some problems are solved best by “old fashioned” procedural program¬ 
ming. In particular, procedural programming is better for procedures that are 
highly algorithmic or computationally intensive. 

Where to Go Next 

The next chapter describes how THINK Pascal implements object-oriented 
programming. As you’ll see, it’s a fairly straightforward extension of record 
declarations. 

If you’re not familiar with object-oriented programming, scan through Chap¬ 
ter 4, then try the “LearnOOP” tutorial in Chapter 5. 

Chapter 7 is about the THINK Class Library, a collection of classes you can 
use to implement Macintosh applications. 

Chapters 9-70 describe the main classes of the THINK Class Library in detail. 
Though these chapters are meant for reference, you might want to leaf 
through some of the class descriptions to get a sense of how the THINK 
Class Library is put together. 
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his chapter shows you how to use the object-oriented extensions to THINK 
Pascal. You’ll learn how to declare a class, how to declare an object, and 
how to define and call a method. The object-oriented extensions to THINK 
Pascal are based on Object Pascal defined in Object Pascal Reportby Larry 
Tesler, Apple Technical Report No. 1, Apple Computer 1985. 

What you should know 

Before you read this chapter, you should know about object-oriented pro¬ 
gramming. You should know about classes, instances, instance variables, 
and methods. If you need to learn about these things, look at Chapter 3. 
THINK Pascal implements objects as handles, so you should be familiar with 
the Macintosh Memory Manager. If you need to learn about the Memory 
Manager, see Inside Macintosh II, Chapter 1, “The Memory Manager.” 
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Overview 

The Object Pascal extensions are built into THINK Pascal. You don’t have to 
add any files to your project. You can use Object Pascal in applications and 
in desk accessories. When you use Object Pascal in a desk accessory or a 
code resource, be sure that you check the Multi-Segment option in the Set 
Project Type... dialog. 

To use objects, you need to declare a class. A class declaration describes the 
properties of a class and names its instance variables and methods. A class 
declaration doesn’t allocate any space; it just lets the compiler know what a 
class looks like. 


Note 

Some implementations of Object Pascal use the term ob¬ 
ject type instead of class and the term field instead of in¬ 
stance variable. 


After you declare a class, you need to define the methods associated with 
the class. A method is a procedure or function that operates on objects of a 
particular class. A method definition is almost identical to a procedure or 
function definition. 

To use objects in a program, you declare a variable, called an object refer¬ 
ence, that will point to the actual object. Then you use the new procedure to 
allocate memory for the object. 

Once you’ve created an object, you can access its instance variables and 
send it messages. When you’re finished using an object, you use the 
dispose procedure to expunge it from memory. 

The sections below talk about each of these steps in detail. 

Declaring a Class 

A class declaration is like a record declaration. You give the class a name and 
specify its superclass, then you declare the instance variables and methods 
like this: 

class = object ( superclass) 
instance variable declarations 
method declarations 
end; 
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The class declaration must specify a class name. If the class has no super¬ 
class, it’s called a root class. To specify that a class is a root class, leave out 
the superclass name after the object keyword. 

After the class name, declare the instance variables and methods. To declare 
an instance variable, use the same syntax you use to declare a field in a 
record. To declare a method, use the same syntax you use to declare a pro¬ 
cedure or function. 

Here are some class declarations: 

Window = object theWindow: WindowPtr; 
growRect: Rect; 
dragRect: Rect; 

procedure Init; 
procedure Destroy; 
procedure Hit(where: Point); 
procedure Drag(where: Point); 
procedure Draw; 
end; 

MyWindow = object (Window) 
windowData: Handle; 
subwindow: ToolWindow; 

procedure Hit(where: Point); 
override; 
procedure Draw; 
override; 
end; 

The first class declaration specifies a root class called Window. It has three 
instance variables and five methods. The second class declaration specifies a 
subclass of Window called MyWindow. The second class inherits all of the 
instance variables that Window declares, as well as all of its methods. 
MyWindow also declares an instance variable of its own and overrides the 
Hit and Draw methods. 

When you override a method in Object Pascal, you must follow the method 
declaration with the word override. If you don’t, you will get an error. 
Object Pascal assumes that all method declarations introduce new methods. 
If you don’t use the word override, Object Pascal thinks that you’re trying 
to introduce a new method with the same name as an inherited method. 

An instance variable in a class declaration can be an object reference. The 
subwindow instance variable in the example above is of class ToolWindow, 


You might want to make all 
your objects be descen¬ 
dants of TObject. See "Us¬ 
ing TObject" on page 33. 
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which hasn’t been defined yet. It may not even be defined in this file. A for¬ 
ward reference like this is always allowed in a class declaration. 


Warning 

A forward reference to a class must resolve to a class. It 
should not resolve to any other type 


Declaring and Using Objects 

Once you’ve defined a class, you can use its name to define an object refer¬ 
ence. An object reference is just like a pointer, but you don’t use the ~ sym¬ 
bol. This is how you define an object reference: 

var 

object: class; 

An object reference definition doesn’t allocate memory for the object. To al¬ 
locate memory for an object, you use the new procedure described later. 

THINK Pascal actually implements object references as handles. You can use 
any of the Macintosh Memory Manager calls that work on handles on objects 
if you type cast the object to a generic handle. The section “Objects and the 
Macintosh” on page 35 tells you why you might want to do this. 

Two objects of different classes are type-compatible if one class is an ances¬ 
tor of the other. For assignment, this works in only one direction: an object 
may be assigned to an ancestor, but not to a descendant. 

For example, assume that TCircle is a subclass of the class TShape and that 
aCircle is an object reference of type TCircle and a Shape is an object ref¬ 
erence of type TShape. This assignment is OK: 

aShape := aCircle 

since the class of aShape is an ancestor of the class of aCircle.This as¬ 
signment is not OK: 

aCircle := aShape 

since the class of aCircle is not an ancestor of the class of aShape. This 
assignment may be OK: 

aCircle := TCircle(aShape) 
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Type casting makes a Shape appear to be of class TCircle, but if range 
checking is on, you’ll get an error at run time if a Shape isn’t really of class 
TCircle. 

Creating and deleting objects 

Before you can use an object, you must create it to allocate space for it in the 
heap. When you’re done with an object, you’ll probably want to delete it to 
reclaim its space. The standard procedures new and dispose create and 
delete objects. 

To create an object use the new procedure like this: 
var 

myObject: TheClass; 
begin 

new(myObject); 
end; 

If your object is a descen- To delete an existing object, use the procedure dispose like this: 

dant of TObject, you can 

send it a Free message to dispose (myObject) ; 

delete it. See "Using TOb - 

ject" on page 33. These two procedures are defined in Runtime. lib. 

Referring to instance variables 

To refer to an instance variable of an object, you use the same syntax as 
when you refer to a field of a record: 

object, member 

Since an object reference is implemented as a handle, THINK Pascal does 
the necessary dereferencing for you. 

As a rule, only the methods of a class should access an object’s instance vari¬ 
ables. Your class declaration should provide methods for getting and setting 
the values of the most important instance variables. 

Class membership 

To test whether an object is a member of a class, use the member function: 
member (anObject, aClass) ; 

This function returns TRUE if the object belongs to the specified class or if 
the class is an ancestor of the object’s class. 
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Defining and Using Methods 

You define a method the same way you define a procedure or function, ex¬ 
cept that you include the class name before the method name like this: 

procedure class . method(parameter declarations) ; 
begin 

procedure body 
end; 

or like this: 

function class . method (parameter declarations) : return-type ; 
begin 

function body 
end; 

If you use a function to implement a method, use the name of the method 
without the class name to set the return value. 

Referring to the current object 

Within a method, the compiler supplies an implicit declaration so you can 
refer to the object that received the message: 

var 

self: class; 

The symbol self refers to the object receiving the message. Within a meth¬ 
od definition, you can omit self when you refer to an instance variable or 
when you call a method in the same class as self. Think of the body of a 
method as being enclosed like this: 

with self do 
begin 

method body 
end; 


Warning 

Because of this implicit with statement, it is never safe to 
take the address of an instance variable. See “Objects and 
the Macintosh” on page 35. 
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A monomorphic method is 
a method that does not 
override another method 
and is never overridden it¬ 
self. 


Here’s what a method declaration for the Window class above might look 
like: 


procedure Window.Drag (where: Point); 
var 

myDragRect: Rect; 
begin 

myDragRect := dragRect; 

DragWindow(theWindow, where, myDragRect) 
end; 

In this example, dragRect and theWindow are both instance variables. 
You could refer to them as self. dragRect and self. theWindow, but 
since the body of the method is surrounded in an implicit with statement, 
you don’t have to use self. 


Note 

If you declare a local variable with the same name as an in¬ 
stance variable, you won’t be able to refer to it because of 
the implicit with statement. 


Calling a method 

To call a method (to send a message to an object), you use this syntax: 
object, method ( parameters) 

When you send a message to an object, THINK Pascal generates a call to a 
run-time dispatcher to find out which method it should use. If the method is 
monomorphic, the linker bypasses the dispatcher and generates a call direct¬ 
ly to the method. 

Calling an inherited method within a method 

Within a method definition, you may want to use the superclass’s method. 
For example, to add functionality to a method, you use the superclass’s 
method, then add more code to augment the behavior. This is how you call 
a superclass’s method: 

inherited method(args) ; 


Note 

When you call an inherited method, THINK Pascal always 
bypasses the message dispatcher and generates a direct 
call. 
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Using TObject 

Your THINK Pascal package includes a file called Ob jlntf. p which con¬ 
tains the definition of a root class called TObject. This class is an abstract 
class that implements methods for copying and deleting any object. You 
might want to make all your classes descendants of TObject. 

This is what the declaration of the TObject class looks like: 

type TObject = object 

function ShallowClone:TObject: TObject; 

{ Lowest level method for } 

{ copying an object; } 

{ Should not be overridden } 

{ except in very unusual cases. } 

{ Simply calls HandToHand } 

{ to copy the object data.} 
function Clone:TObject: TObject; 

{ Defaults to calling ShallowClone; } 

{ Can be overridden to copy objects } 

{ refered to by fields.} 
procedure ShallowFree:TObject; 

{ Lowest level method for } 

{ freeing an object; } 

{ Should not be overridden } 

{ except in very unusual cases. } 

{ Simply calls DisposHandle } 

{ to free the object data. } 
procedure Free:TObject; 

{ Defaults to calling ShallowFree; } 

{ Can be overridden to free } 

{ objects refered to by fields.} 
end; 

If you make all your classes descendants of TObject, you can send any ob¬ 
ject a Clone message to copy it or a Free message to delete it. 


Warning 

If you send an object a Free message to delete it, do not 
use the dispose procedure on the same object. If you do, 
your program will crash. Conversely, if you clone an object, 
you don’t need to use the new procedure. 
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Your own classes can override the Clone and Free methods to copy or to 
free memory that your objects allocate. For instance, suppose you have a 
class that allocates a table as a handle: 

FixedTable = object (TObject) 
theTable: Handle; 
numltems : integer; 

procedure Init; 

function Clone: FixedTable; 

override 

procedure Free; 

override 


end; 

Assume that the Init method allocates a block of IK bytes like this: 

procedure FixedTable.Init; 
begin 

theTable := NewHandle(1024); 
numltems := 0; 
end; 

Your Clone and Free methods might look like this: 

function FixedTable.Clone: FixedTable; 
var 

objCopy: FixedTable; 
tableCopy: Handle; 
begin 

objCopy := nil; 

{ HandToHand may move memory, } 

{ and it takes a VAR parameter, } 

{ so make a copy of the handle. } 
tableCopy := Handle(theTable); 

{ now see if there's enough room } 

{ for the table. } 

if HandToHand(tableCopy) = noErr then 
begin 

{ now copy the object if possible } 
objCopy := inherited Clone; 
if objCopy <> nil then 

{ assign the table if the copy is OK } 
objCopy.theTable := tableCopy 
else 

{ otherwise get rid of the table } 
DisposHandle (tableCopy); 

end; 
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{ return the result } 

Clone := objCopy; 
end; 

procedure FixedTable.Free; 
begin 

{ Release any storage that } 

{ this object allocated } 
DisposHandle(theTable); 

{ Now use the inherited method } 
{ to delete this object } 
inherited Free; 
end; 


Note that the Clone method is careful about not passing a VAR parameter to 
a routine that may move memory. 

Tips and Techniques 

This section describes some general tips to make writing object-oriented 
programs easier. It describes how to organize your classes, how to initialize 
objects easily, and how to make sure that your objects behave correctly un¬ 
der the Macintosh Memory Manager. 

Organizing your classes 

It’s a good idea to isolate classes to make them easy to use and reuse. The 
best way to do this is to make each class a unit. If you have several classes 
that are all related, you can put them all into one large unit. Another way to 
organize your classes is to put the class declarations in one or two interface 
files and to put the implementation for each class in a separate file. 


To learn about units, see 
Chapter / 0, "Units and Li¬ 
braries, " in the THINK Pas¬ 
cal User Manual. 

To learn more about seg¬ 
mentation and setting at¬ 
tributes, see Chapter 7, 

"Working with Projects," 
of the THINK Pascal User 
Manual. 


For example, the THINK Class Library included with your THINK Pascal 
package contains about 60 core classes. The class definitions are in the file 
TCL. p. The implementations for each of the methods are in separate files. 

Objects and segments 

THINK Pascal creates two directive entries, «%_MethTables» and 
«%_SelProcs», that contain the routines and data for the message dis¬ 
patcher. By default, these directive entries are in the main segment. If you’re 
using a lot of objects, it’s a good idea to move each of these two segments 
into their own segment and to set their attributes to Locked. 

Objects and the Macintosh 

THINK Pascal implements objects as handles. You can pass an object refer¬ 
ence to virtually any Memory Manager routine that works on handles. 
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An important side effect of this implementation is that any reference to an in¬ 
stance variable is implicitly a handle reference. 

Warning 

Your program should not rely on the addresses of instance 
variables, particularly in calls to Toolbox routines that may 
move memory. 

Look at the definition for the Drag method for the Window class declared 
earlier in this chapter: 

procedure Window.Drag(where: Point); 
var 

myDragRect: Rect; 
begin 

myDragRect := dragRect; 

DragWindow(theWindow, where, myDragRect); 
end; 

The more obvious definition would be: 

procedure Window.Drag(where: Point); 
begin 

DragWindow(theWindow, where, dragRect); 
end; 

Because the third argument to DragWindow is a var parameter, dragRect 
refers to the address of the instance variable self . dragRect. Since the 
DragWindow routine may move memory— including the handle self— 
you can’t rely on the address of dragRect being correct when 
DragWindow needs it. 

The first definition, which copies the instance variable into a local variable, 
avoids the problem since the address of a local variable never changes with¬ 
in the method body. 

It is OK to assign values to instance variables, even when the expression on 
the right hand side may move memory. For instance, consider this class dec¬ 
laration: 

FixedTable = objecttheTable: Handle; 
numlterns: integer; 

procedure Init; 

end; 
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Assume that the Init method allocates a block of IK bytes like this: 

procedure FixedTable.Init; 
begin 

theTable := NewHandle(1024); 
numlterns := 0; 
end; 

In this case, the assignment to theTable is safe. THINK Pascal calls 
NewHandle before it resolves the reference to theTable. 

Of course, you can use the Memory Manager routines HLock and HUnlock 
and HGet State and HSetState to keep the handle self from moving 
around. Keep in mind that using the Memory Manager will slow your pro¬ 
gram down. 


Note 

If you use the Memory Manager routines to lock and un¬ 
lock an object, be sure to coerce it to the generic Handle 
type like this: HLock (Handle (self) ). 


You can use the Macintosh Toolbox routine GetHandleSize to find out 
how big an object is. The size of an object is the sum of the sizes of all of its 
instance variables, including its ancestors’ instance variables, plus 2 bytes (4 
bytes if you’re using the Far Code option). 


Warning 

Your program should not rely on the size of an object or the 
representation of an object in memory. 


Keywords 

Object Pascal reserves the keywords object and inherited. The word 
override is not a keyword, but THINK Pascal interprets it specially in con¬ 
text 

Summary 

This is a summary of the functions and procedures you use to work with ob¬ 
jects. These routines create objects, destroy objects, and test membership. 

procedure new (object Reference) ; 

Create a new instance of an object with the class of the variable objectRefer- 
ence. 
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procedure dispose (objectReference) ; 

Delete the specified object This procedure releases the memory that the ob¬ 
ject occupies. It does not release any memory that an instance variable might 
point to. 

function member (objectReference, class) : Boolean; 

Return TRUE if objectReference is a member of class. An object is a member 
of a class if it is of type class or if class is a superclass of the object’s actual 
class. 

If your classes are descendants of TObject, you can use these methods to 
copy and delete objects. 

function TObject.Clone: TObject; 

Return a new object that is a copy of the object receiving a Clone message. 
For example: 

var 

myObject: MyClass; 

{ MyClass is a descendant of TObject } 
anObject: MyClass; 
begin 

new(myObject); 

{ Create the object with new } 

some operation on myObject 

anObject := myObject.Clone; 

{ Create a copy of myObject } 
end; 

procedure TObject.Free; 

Delete the object that receives the Free message. Don’t call dispose on an 
object that you’ve freed with this message. For example: 

var 

myObject: MyClass; 

{ MyClass is a descendant of TObject } 

begin 

new(myObject); { Create the object } 

myObject.Free; { Delete the object } 

end; 
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Tutorial: 
LearnOOP % 


Ije arnOOP is a shape-drawing program that introduces you to the basics of 
object-oriented programming. Each of the shapes that LearnOOP draws is an 
object. You’ll see how the routines that operate on objects are encapsulated 
in the class declaration. You’ll learn how dynamic binding and how inherit¬ 
ance work. Then you’ll define a new class yourself. 

If you already know object-oriented programming, you don’t have to read 
this chapter. You should skip on to the next chapter to learn about the class 
browser. 

Before you begin 

Make sure that you’ve installed THINK Pascal on your Macintosh as de¬ 
scribed in Chapter 2 of the THINK Pascal User Manual. You don’t need to in¬ 
stall the THINK Class Library to run this tutorial. 

What you should know 

This tutorial assumes that you know how THINK Pascal works. You should 
know how to open a project, how to run a project, and how to use the edi¬ 
tor. If you need to learn how to do any of these things, see the tutorial in 


Chapter 3 of your THINK Pascal User Manual. 

Contents 

What Does LearnOOP Do? . . 41 

How Does LearnOOP Work?. .43 

How Do Objects Know How to Draw Themselves? . . 44 

How Do You Create an Object? . . 49 

How Do You Define a New Class? . 50 

But How Does It Know? . . 52 

Where to Go Next . . 52 
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What Does LearnOOP Do? 

To begin this tutorial, double-click on the LearnOOP . n project in the 
LearnOOP folder. If you’re already in THINK Pascal, close any existing proj¬ 
ect, and choose LearnOOP .n from the standard file dialog. The project win¬ 
dow looks like Figure 5-1. 


Options 

I LearnOOP. tt m 

File (by build order) 

Size 

1 


Runtime .lib 

0 



Interface .lib 

0 

IS1 

[DlfHl V R 

Objlntf.p 

0 


[MSv r 

UShapes.p 

0 

■ 

fPlfNI V R 

LearnOOP .p 

0 



To tel Code Size 

0 

1 




a 

0 



Q| 


Figure 5-1 The LearnOOP.7t project 


Choose Go from the Run menu to start the program. THINK Pascal will load 
the libraries and compile the source files before it starts running. It will take 
a minute or so. 

The LearnOOP program uses the Text window to prompt you for something 
to do, and it draws in the Drawing window. When you run the program, 
LearnOOP asks you if you want to create an Oval or a Rectangle, like in Fig¬ 
ure 5-2. 


Te«t 


Create Ooal or Rectangle? 
IO/R/Q1 : 


K> 


Q 


Figure 5-2 Asking for a shape 


If you want to draw an oval, type an 0; if you want to draw a rectangle, type 
an R. To quit the program altogether, type a Q. Right now, type an O. 
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After you tell LearnOOP what kind of shape to draw, it asks you to give it the 
coordinates of the shape, like in Figure 5-2. 


Create Oval or Rectangle? 
[O/R/Q] : 0 
Where? 
t I b r: 


Figure 5-3 Asking for coordinates 

The letters t 1 b r represent the coordinates of the top, left, bottom, and 
right corners of a rectangle that completely encloses the shape. The point 0,0 
is at the top left corner of the window. To see how this works, try typing 
these values: 10 10 4 0 90. LearnOOP draws the shape in the drawing 
window like Figure 5-2. 




2 

a 


Drawing | 






Figure 5-4 Drawing the shape 


After it draws the First shape, LearnOOP asks what kind of shape to draw 
next. Try a couple of more shapes before you look at how the program 
works. 
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How Does LearnOOP Work? 

If LearnOOP is still asking you for a kind of shape, type a Q to make it stop. 

Double-click on the file named LearnOOP . p in the project window. The 
program that draws shapes is pretty simple. Look at the main part of the pro¬ 
gram at the end of the file: 

{ Main Program } 
begin 
ShowText; 

ShowDrawing; 

while ChooseShape(aShape) do 
if aShape = nil then 
writeln('•• I don''t know that shape.') 
else 
begin 

writeln('Where?'); 
write('t 1 b r: '); 

readln(aTop, aLeft, aBottom, aRight); 
aShape.SetBounds(aTop, aLeft, aBottom, 
aRight); 
aShape.Draw 
end; 

writeln('•• FINISHED ••') 
end. 

The first two procedures just make sure that the Text and Drawing windows 
are visible. 

The next part of the program in the while loop actually does the drawing. 
The function ChooseShape is what asks you for the kind of shape to draw. 
If you choose to quit, ChooseShape returns FALSE, and the program ends. 
If you do choose a shape, ChooseShape creates a shape and stores it in the 
variable aShape. 

After you choose a shape, the program asks you for the coordinates of the 
shape and stores them in four variables. 

The next two lines are the most interesting lines of the program. 

The line 

aShape.SetBounds(aTop, aLeft, aBottom, 
aRight); 

sends a SetBounds message to the shape aShape to give it its coordinates. 


Object-Oriented Programming 43 



5 Tutorial: LearnOOP 


The line 

aShape.Draw; 

sends aShape a message to draw the shape. 

The important thing here is that the program uses the same two lines to set 
the coordinates and to draw the shapes regardless of the kind of shape. The 
part of the program that draws the shape doesn’t know what kind of shape 
to draw. It just sends the shape object a Draw message. The object knows 
how to draw itself. 

How Do Objects Know How to Draw Themselves? 

The best way to find out what’s going on is to step through the program. 

If LearnOOP is asking you for a shape, type Q to make the program end. 
Then double-click in the project window on the files LearnOOP .p and 
UShapes . p to open them. If you don’t see a little Stop Sign in the lower left 
corner of the editing windows, choose the Stops In command from the De¬ 
bug menu. Next, in the file LearnOOP . p, put a stop sign on the line that 
sends the Draw message. The window should look like Figure 5-5. 


LearnOOP.p 




ShowText; 

ShowDrawing; 

virile ChooseShape(aShape) do 
if aShape = nil then 
writelnC’ee I don’’t know that shape.’) 

else 

begin 

writelnC’Where?’); 
writeC’t 1 b r: ’); 

readlnCaTop, aLeft, aBottom, aRight); 

aShape.SetBoundsCaTop, aLeft, aBottom, aRight); 
aShape .Draw 

end; 

writelnC’ee FINISHED ee‘) 
end. 




——B^la 


lHif 


Figure 5-5 Putting a stop sign in LearnOOP.p 
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How Do Objects Know How to Draw Themselves? 


Now choose the Go command from the Run menu. 

THINK Pascal starts the program again, and LearnOOP asks you to choose a 
shape. Type R for rectangle. LearnOOP asks you to type in the bounds for 
the shape. Type in whatever you like. (If you can’t think of anything, try 2 0 
30 45 66.) 

As soon as you type the Return key, LearnOOP stops at the line that sends a 
Draw message to aShape. To find out what’s going on, choose the Step 
Into command from the Run menu. You’ll see the THINK Pascal execution 
finger point to the beginning of a procedure called CRectangle .Draw, 
like in Figure 5-6. 



Figure 5-6 Stepping into CRectangle.Draw 

This procedure is actually a method. In fact, it’s the method that handles 
Draw messages sent to objects of class CRectangle. In a moment, you’ll see 
what this class looks like, but first, see what happens when you choose a dif¬ 
ferent kind of shape. 

Choose the Go command from the Run menu to let LearnOOP draw the 
shape. When it asks you for another shape, type O for oval. Type whatever 
you want for the location. Because the stop sign is still in, the program stops 
at the line that sends a Draw message to aShape. Choose the Step Into 
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command from the Run menu again. This time, you’ll see the execution fin¬ 
ger at the beginning of another procedure, as in Figure 5-7. 



Figure 5-7 Stepping into COval.Draw 


The procedure COval .Draw is the method that handles Draw messages for 
objects of class COval. 

The declaration of a class determines how an object will respond to a mes¬ 
sage. Scroll to the beginning of the file UShapes . p. The class declarations 
for the objects are in the interface part: 

type 

{ CShape is the abstract class that } 

{ describes all shapes. All shape classes } 

{ are a subclasses of this class. } 

CShape = object(TObject) 

{ The rectangle that encloses the shape. } 
itsRectangle: Rect; 

{ The SetBounds method sets values for } 

{ itsRectangle. Most subclasses won't } 

{ need to override this method. } 
procedure SetBounds (aTop, aLeft, aBottom, 
aRight: integer); 
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{ The Draw method draws the shape. } 

{ All subclasses should override } 

{ this method. } 
procedure Draw; 
end; 

CRectangle = object(CShape) 
procedure Draw; 
override; 
end; 

COval = object(CShape) 
procedure Draw; 
override; 
end; 

These declarations say that this file has three classes. The first class, CShape, 
is a generic shape. Every object of class CShape has one instance variable: a 
rectangle called itsRectangle. Every object of class CShape also imple¬ 
ments two methods: Set Bounds to set the size of the shape, and Draw to 
actually draw the shape. 

CShape is an abstract class. You use an abstract class as the common ances¬ 
tor of a family of classes that share certain traits and behaviors. The common 
trait that all shapes share is that they need a bounding rectangle. The com¬ 
mon behaviors that all shapes share are being drawn and setting the bound¬ 
ing rectangle. 

The next two classes, CRectangle and COval, are subclasses of CShape. They 
both inherit the itsRectangle instance variable and the SetBounds 
method. Both classes override the Draw method. This means that a CRectan¬ 
gle is identical to a generic shape, but it has its own drawing behavior. COval 
is also identical to a generic shape, but it has its own drawing behavior dif¬ 
ferent from CRectangle’s. 
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Now scroll down to look at the implementation of the methods. These are 
the method definitions for the abstract class CShape: 

procedure CShape.SetBounds (aTop, aLeft, 
aBottom, aRight: integer); 
begin 

with itsRectangle do 
begin 

top := aTop; 
left := aLeft; 
bottom := aBottom; 
right := aRight 
end 
end; 

procedure CShape.Draw; 
begin 

writeln('Shouldn 11 t get here! 1 ) 
end; 

The first method, SetBounds, just sets up the boundary rectangle 
itsRectangle. Since itsRectangle is an instance variable for this 
class, you don’t need to declare it in the var section of the procedure. 

The second method is the generic Draw method. Because CShape is an ab¬ 
stract class, there shouldn’t be an object of class CShape. Every subclass of 
CShape should override the Draw method to draw a particular kind of 
shape. 

The Draw methods for CRectangle and COval override the generic Draw 
method with the specific behavior for their class. 

procedure CRectangle.Draw; 
begin 

FrameRect(itsRectangle) 
end; 

procedure COval.Draw; 
begin 

FrameOval(itsRectangle) 
end; 

These are the two procedures you saw when you stepped through the pro¬ 
gram. They’re what give CRectangle and COval their unique drawing behav¬ 
ior. 

If you send an object of class CRectangle a Draw message, the 
CRectangle .Draw method gets called, and the FrameRect procedures 
draws a rectangle. If you send an object of class COval a Draw message, the 
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COval .Draw method gets called, and the FrameOval procedure draws an 
oval. 

How Do You Create an Object? 

The specific Draw method that gets called when you send an object a Draw 
message depends on the class of the object. So, how do you create objects of 
different classes? 

Look at the ChooseShape function in the file LearnOOP .p. This is the 
function that asks you to choose the shape: 

function ChooseShape (var theShape: CShape): 

Boolean; 

begin 

ChooseShape := TRUE; 

writeln('Create Oval or Rectangle?'); 
write('[0/R/Q] : '); 

readln(answer); 

case answer[1] of 'Q', 'q': 

ChooseShape := FALSE; 

'R', 'r': 

new(CRectangle(theShape)); 

'O', 'o': 

new(COval(theShape)); 
otherwise 
theShape := nil 

end 

end; 

After it asks you for the kind of shape to draw, this function looks at what 
you typed and returns an object of the appropriate class. 

If you typed an R or an 0, it uses the Pascal procedure new to create a new 
object. 

Note that the var parameter theShape is declared as class CShape. When 
it creates the shape, the function first type casts it to class CRectangle or to 
class COval. So this line: 

new(CRectangle(theShape)); 

means “Treat theShape as a CRectangle and create an object of that class.” 

The rules for assignments of objects say that you can assign an object of a 
subclass to a variable declared as a superclass. What this means is that you 
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can assign a CRectangle object to a variable of class CShape, but you can’t 
assign an object of class CShape to variable of class CRectangle. 

After it creates the shape, ChooseShape returns the new object, and the 
object gets set to the global variable a Shape in the while loop: 

while ChooseShape(aShape) do 

The class of aShape is CShape. Doesn’t this mean that when you send a 
Draw message to aShape it should call the generic CShape .Draw method? 
No, because the class of an object is determined at run time. This is called 

dynamic binding. 

So if you create an object of class CRectangle and send it a Draw message, 
the method that gets called is CRectangle .Draw. 

What happens when you send the Set Bounds message? Since neither the 
CRectangle class nor the COval class override the SetBounds method, the 
generic CShape . SetBounds method gets called when you send either 
class of object a SetBounds message. This is called inheritance. The 
CRectangle and COval classes inherit the SetBounds method from their su¬ 
perclass, CShape. 

How Do You Define a New Class? 

Now, why don’t you try creating a new class that’s a subclass of one of the 
existing three classes. Here’s an example of how to do it. You’ll create a sub¬ 
class for drawing squares. 

The first thing to do is to decide which class to subclass. Since a square is just 
like a rectangle— except that it has sides of equal lengths— try making the 
square a subclass of CRectangle. You can use the same drawing method, but 
you’ll have to override the SetBounds method. Here’s how you’d declare 
the new CSquare class: 

If you want to follow along, 
put this class declaration 
right under the COval dec¬ 
laration in the file 
UShapes. p. 


CSquare = object(CRectangle) 

procedure SetBounds (aTop, aLeft, aBottom, 
aRight: integer); 
override; 
end; 
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If you want to follow along, 
put this method definition 
right under the 
COval. Draw definition in 
the file UShapes .p. 


♦ 


And here’s one way of defining the SetBounds method for the CSquare 
class: 

procedure CSquare.SetBounds (aTop, aLeft, 
aBottom, aRight: integer); 
begin 

aRight := aLeft + (aBottom - aTop); 
inherited SetBounds(aTop, aLeft, aBottom, 
aRight) 
end; 

This procedure says to reset the right edge of the bounding rectangle to be 
the same distance from the left edge as the bottom edge is from the top 
edge. (It ignores whatever value you give it for aRight.) The next line says 
to use the superclass’ SetBounds method. In this case, it means to call 
CRectangle’s SetBounds method which it inherits from CShape. 

The only thing left to do is to edit the ChooseShape function in the file 
LearnOOP .p to handle the new shape. Here’s how: 

function ChooseShape (var theShape: CShape): 

Boolean; 

begin 

ChooseShape := TRUE; 

writeln(*Create Oval, Rectangle, Square?*); 
write(*[0/R/S/Q] : *); 

readln(answer); 

case answer[1] of 

•Q\ *q' : 

ChooseShape := FALSE; 

'R*, 1 r': 

new(CRectangle(theShape)); 

*0*, 'o *: 

new(COval(theShape)); 

*S*, * s * : 

new(CSquare(theShape)); 
otherwise 
theShape := nil 
end 
end; 

Try running the program now with the new class. When you ask 
ChooseShape to create a square, it should ignore the value you give for the 
right edge of the bounding rectangle. 
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Note 

Because of the way LearnOOP reads the coordinates of the 
bounding rectangle, you still have to provide a value for 
the right edge. 


But How Does It Know? 

Even though you’ve seen object-oriented programming work, you may still 
be wondering who or what in the LearnOOP program is calling the right 
method for a given message. Yes, there is a mechanism that figures out 
which method goes with which message for a particular object. But this 
mechanism is abstracted away in the compiler and becomes part of the lan¬ 
guage. 

Here’s an example. You probably know that most microprocessors use dif¬ 
ferent machine language instructions for multiplying integers and for multi¬ 
plying floating point numbers. But when you write a Pascal program you 
know that you can write a statements like: 

floatVar := 1961.0102 * floatVal; 
count := 24 * intVal; 

Though there’s a “hidden mechanism” that knows when to use floating 
point multiplication and when to do integer multiplication, you don’t worry 
about it. The inner workings of the multiplication operator are abstracted 
away and become a part of the language. 

It’s the same thing with object-oriented programming. The mechanism that 
matches messages and methods with objects is a part of the language. The 
power of object-oriented programming comes not from how it works but 
from the layer of abstraction that it adds to the low level mechanics of data 
structures and algorithms. 

Where to Co Next 

Since this small program declares only three classes, this is a good time to 
learn how to use the Class Browser. Chapter 6 describes the Class Browser in 
detail. 

If you want, you can try adding more methods or classes. Try adding a meth¬ 
od that asks where to put the shape so you don’t have to provide an extra 
value for the CSquare class. Or you might want to try adding methods for 
filled shapes or for shapes with different line thicknesses. 
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T 


his chapter shows you how to use the class browser. The class browser is a 
tool that displays all the classes defined in your project as a tree chart. You 
can use the Class Browser to look at the declaration of classes or to find the 
definitions of methods. 


Contents 

Using the Class Browser ... .55 

Finding the Declaration of a Class. .55 

Finding a class declaration with the Class Browser . 55 

Finding a class declaration with the editor ... .56 

Finding the Definition of a Method. .57 

Finding a method definition with the Class Browser . . 57 

Finding a method definition with the editor .... .58 

Keyboard Shortcuts in the Class Browser . . 59 

Class Browser Summary . . .60 
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Using the Class Browser 

To use the browser, choose the Class Browser command from the Win¬ 
dows menu. The Class Browser is shown in Figure 6-1. 



Figure 6-1 The Class Browser 


The boxes represent the class hierarchy of the classes in your project. Each 
box represents one class. Subclasses are connected to their superclasses like 
an organizational chart. 

In this picture, you can see that the classes CDesktop, CPane, and CWindow, 
are all descendants of CView. 

Finding the Declaration of a Class 

You can find the definition of a class two ways: with the Class Browser or 
with the editor. 

Finding a class declaration with the Class Browser 

To find the declaration of a class, double-click on the box that represents the 
class. The editor opens the file that contains the class declaration and scrolls 
to the declaration of the class. 
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For instance, to see the declaration of the CBureaucrat class, double-click on 
the CBureaucrat box. The editor opens the file CBureaucrat. h and scrolls 
to the declaration of CBureaucrat, as shown in Figure 6-2. 


TCL.p 


ggUBSBBZH = OBJECT (CCoI laboratory 


K> 


itsSuperoisor: CBureaucra t; 

PROCEDURE I Bureaucrat <aSupervisor: CBureau 

PROCEDURE Free; 

OUERRIDE; 

FUNCTION GetSuperuisor: CBureaucrat; 

PROCEDURE Notify <theTask: CTask); 

PROCEDURE DoKeyDown CtheChar: Char; 

keyCode: Byte; 
macEoent: EuentRe 

PROCEDURE DoRutoKey CtheChar: Char; 

keyCode: Byte; 
macEoent: EuentRe 

PROCEDURE DoKeyllp CtheChar: Char; 

keyCode: Byte; 
macEoent: EuentRe 

PROCEDURE DoCommand CtheCommand: Longint); 

PROCEDURE Dawdle CURR maxSIeep: Longint); 

PROCEDURE UpdateMenus; 

FUNCTION BecomeGopher CfBecoming: Boolean): 

PROCEDURE BroadcastChange Creason: Longint; 

info: UN IU Ptr); 

OUERRIDE; 

PROCEDURE Prou i derChanged 


CaProuider: CCoI I 
reason: Longint; 
info: UN IU Ptr); 


o 


Q 


Figure 6-2 The declaration of CBureaucrat 


Finding a class declaration with the editor 

You can find the declaration of a class in the editor the same way you find 
the definition of a procedure or function. When you hold down the Option 
key as you double-click on the name of a class, the editor opens the file that 
declares that class. 

For example, if you’re looking at the CEditPane. IEditPane method, 
and you want to see the declaration of the CBureaucrat class, you can Op¬ 
tion-double-click on the name CBureaucrat in the parameter list. 
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Finding the Definition of a Method 

You can find the definition of a method two ways: with the Class Browser or 
with the editor. 


Finding a method definition with the Class Browser 

To find all the methods that a class defines or overrides, hold the mouse 
down on the class name. A pop-up menu appears next to the class. 


Class Browser 


A C Application h|~~ CEditApp 1 


A CBureaucrat \ 


llaboratorH 


r j CDirectorQwnerH 




J mirvhrtard 1 


director 


4 CView 1H~ CPane 


^ CDesktop | 


M CWindow | 




, ___ rl CCluster Ml 

CCollection HZ C*rr«g j j====^ 

I 




Figure 6-3 The methods of CDirector 
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If you choose a method from the pop-up menu, the editor opens the file that 
defines the method. 


Note 

The pop-up menu shows only the methods that a class de¬ 
fines or overrides. The pop-up menu does not include the 
methods that the class inherits from its superclass. 
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Finding a method definition with the editor 

You can find the definition of a method from the editor the same way you 
can find the definition of a procedure or function. When you hold down the 
Option key as you double-click on the name of a method, the editor opens 
the file that defines that method and scrolls to the method definition. 

Since several classes may define or override the same method, it’s not clear 
which file the editor should open. When a method is defined in more than 
one class, the editor opens the Class Browser window and highlights the 
classes that define the method with a bold border. 

For example, suppose that you Option-double-click on the method name 
ChangeSize in the CEditPane. IEditPane method, like in Figure 6-4 



Figure 6-4 Option-double-clicking on the call to the ChangeSize method. 


Since several classes define the ChangeSize method, the editor opens the 
Class Browser window and highlights the classes that define the method as 
shown in Figure 6-5. 


Class Browser 


CDesktop 1 


■ 1 CControl H CScrollBarH 

I i a i ■ . i 


CAbstractTexthl CEc 


,---,H CAbstractText 

r CView I!" CPane I CPictur* I 


k i...£.6r:.t:Wr 


CSizeBox | 

^ CWindow | 

■jj CCIuster 1-1 CList ~] 


o 




Figure 6-5 The classes that define a ChangeSize method. 
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Keyboard Shortcuts in the Class Browser ^ 

To see the definition of the method, double-click on one of the highlighted 
classes. The editor opens the file that defines that method. 

If you picked the wrong class or if you want to see another definition of the 
method, you can Option-double-click on the method name again to display 
the Class Browser window again. 

Keyboard Shortcuts in the Class Browser 

You can use the keyboard to navigate through the classes in the Class 
Browser window. The keyboard commands let you select classes or find the 
definitions of classes without using the mouse. 

If you type the name of a class, the Class Browser highlights the class whose 
name matches what you’ve typed so far. For instance, as you type “CCon- 
trol”, the browser highlights CObject, CChore, CCollaborator, and finally 
CControl. 


This is what other keys do in the Class Browser: 


Key 

Enter or Return 


Up Arrow 

Down Arrow 
Left Arrow 
Right Arrow 
Tab 


Action 

Open the file that contains the definition 
of the selected class. This is the same as 
double clicking on a class name. 

Select the previous sibling of the current 
class. 

Select the next sibling of the current class. 
Select the superclass of the current class. 
Select a subclass of the current class. 
Traverse each class in the class hierarchy. 
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Class Browser Summary 

This table summarizes how to use the Class Browser: 


If you’re 
in the... 

Class Browser 

and you want 
to find a... 

class declaration 

do this: 

double-click on the class 

name. 

Editor 

class declaration 

Option-double-click on 
the class name. 

Class Browser 

method definition 

hold down the mouse to 
see a pop-up menu of all 
the methods the class de¬ 
fines or overrides. Choose 
a method name from the 
pop-up menu to see its 
definition. 

Editor 

method definition 

Option-double-click on 
the method name. If there 
is more than one defini¬ 
tion, the Class Browser 
highlights all the classes 
that define the method. 
Double-click on the class 
name to see the definition 
of the method. 
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T 


he THINK Class Library is a collection of classes that implement a standard 
Macintosh application. If takes care of things like handling menu com¬ 
mands, updating windows, dispatching events, dealing with MultiFinder, 
maintaining the Clipboard, and so on. 


Contents 

Introduction. 

What you should know 

Conventions. 

Types. 

Naming conventions .... 
Object-oriented terminology . . 

Overview. 

The class hierarchy. 

The visual hierarchy .... 
The chain of command . . . 

The flow of control. 

Writing a n Application with the TCL . . 

Creating the project in THINK Pascal 
Creating the project in THINK C . . 

Creating the application subclass 
Creating the document subclass . . 

Creating the pane subclass . . . 

Working with Panes. 

Windows and panes .... 

Coordinate systems. 

Drawing in a pane. 

Properties of panes. 

Panoramas. 

Scroll panes. 

Cursor tracking. 

Initializing views from resources 

Working with Menus .... 

Using MENU resources . . 

Building menus on the fly . 
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-- 

Introduction 

This chapter introduces you to the THINK Class Library and talks about 
some of the general topics in application building. After you read this chap¬ 
ter, you should try running the demonstration applications. Be sure to follow 
the instructions in Chapter 2 of your user manual, and in this manual’s Chap¬ 
ter 2, “Installing the THINK Class Library” to installs the THINK Class Library 
and its demonstration programs. 

What you should know 

You should be comfortable working with THINK C or THINK Pascal. You 
should be familiar with the fundamentals of Macintosh programming. Partic¬ 
ularly, you should know about QuickDraw, the Window Manager, and the 
Memory Manager. 

If you’re using THINK C, you should be familiar with the THINK C imple¬ 
mentation of objects. If you’re using THINK Pascal, you should know Object 
Pascal. Earlier chapters in this manual cover these topics in detail. If you 
need a fundamental introduction to object-oriented programming, see Chap¬ 
ter 3, “Object-Oriented Programming.” As you go through this chapter, re¬ 
member that this is all new territory, so don’t be discouraged if it takes a 
while for all the pieces to fall into place. 

Conventions 

This manual is designed for both the THINK C and THINK Pascal versions of 
the THINK Class Library. The chapters that follow describe the classes in the 
THINK Class Library. The chapters are organized like this: 

Section Description 

Introduction A brief description of the class. 

Heritage The class’s superclass and its subclasses. 

Using A detailed description of how to use the 

class, along with examples. 

Variables A list of the instance variables of the class. 

Methods A description of each method that the 

class implements or overrides. 

Types 

Most of the types used to declare instance variables are the same in C and in 
Pascal. For 32-bit integers and 16-bit integers, this manual uses the Pascal 
names. C programmers should assume the corresponding C type: 
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Pascal type C type 

integer short 

longint long 

Hexadecimal values use C syntax: OxOFA is the same as $0FA in Pascal. 

In Pascal a pointer that doesn’t point to anything has a special value called 
NIL. In C the same value is called NULL. This manual uses both terms. 

Naming conventions 

The THINK Class Library follows these naming conventions: 


Name 

Description 

CName 

The name of a class. 

OName 

The name of a class that was defined in 
the original version of the THINK Class Li¬ 
brary, but replaced in this version. 

aName 

A formal parameter. 

cName 

A class variable. 

fName 

A flag. Usually a Boolean instance 
variable. 

gName 

A global variable. 

kName 

A constant. In Pascal these are defined as 
const. In C these are defined with 
#def ine or enum. 

itsName 

An instance variable. 

theName 

A variable. Usually a local variable or an 
instance variable. Sometimes used for for¬ 
mal parameters. 

macName 

A Macintosh data structure used either as 
an instance variable or as a local variable. 


Object-oriented terminology 

This manual uses the terminology established in Chapter 3, “Object-Orient¬ 
ed Programming” to talk about object-oriented programming. 

The syntax for calling a method inherited from the superclass is slightly dif¬ 
ferent between C and Pascal, so this manual uses the phrase “call the inherit¬ 
ed method.” In THINK C, you would call it like this: 

inherited::MethodName(); 

In THINK Pascal, you’d call it this way: 

inherited MethodName; 
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Overview 

The THINK Class Library is organized into three distinct, interacting struc¬ 
tures: the class hierarchy, the visual hierarchy, and the chain of command. 
The class hierarchy is the set of all the classes that make up the THINK Class 
Library. The visual hierarchy describes the organization of all visible entities. 
The chain of command specifies which objects get to handle commands. 

The THINK Class Library converts Macintosh events into visual messages 
and direct commands. A visual message is an event that affects the visual 
hierarchy. Mouse clicks, activate events, and update events are all visual 
messages. A direct command is a request that an object perform an action. 
Direct commands are usually the result of menu commands. 

To convert Macintosh events into messages and commands, the THINK 
Class Library uses an object called a switchboard. The switchboard calls 
GetNextEvent or WaitNextEvent repeatedly and, depending on the 
kind of event, sends a message to the appropriate object. Each application 
has only one instance of a switchboard object. Another object, called the 
bartender, takes care of converting menu selections into direct commands. 

The class hierarchy 

The class hierarchy describes the relationships among all the classes in the 
THINK Class Library. All of the classes are descendants of the root class 
CObject. The class hierarchy is in Figure 7-1 on page 68. To make the draw¬ 
ing easier to read, the initial ‘C of each class is omitted. 


Note 

The classes with a heavy outline constitute the core classes 
that must be present in any program that uses the THINK 
Class Library. 


Do not think of the class hierarchy as a functional description of the THINK 
Class Library. You might think from the drawing of the class hierarchy that 
the CRadioGroup class somehow interacts with the CBureaucrat class, but 
that’s not the case. 

Instead, think of the class hierarchy as a family tree. Each class inherits all of 
the behavior (methods) and all of the attributes (instance variables) of its an¬ 
cestor. So the CButton class is a control. It behaves like a control and re¬ 
sponds to all of the messages a control responds to. 

Some of the classes in the class hierarchy are abstract classes. The THINK 
Class Library never creates objects of these classes. They’re used to give a 
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Figure 7-1 The THINK Class Library's class hierarchy 
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Overview 


family of objects common behaviors. The most important abstract classes in 
the THINK Class Library are CObject, CCollaborator, CBureaucrat, CView, 
CDirectorOwner, and CApplication. 

The visual hierarchy 

The visual hierarchy describes all the visible objects, or views, that the 
THINK Class Library knows about. The visual hierarchy is built around the 
idea of enclosures. Everything that you see on the screen belongs to—is 
enclosed by—another visual entity. 

At the top of the visual hierarchy is the desktop. The desktop encloses all of 
the windows in an application. Each window encloses one or more panes, 
and those panes may enclose other panes. Figure 7-2 shows a typical visual 
hierarchy. 



Figure 7-2 A typical visual hierarchy 

Unlike the class hierarchy, the visual hierarchy is dynamic. It changes as 
your program runs. When you open a new document, you add another win¬ 
dow to the desktop, and you add another set of panes to the new window. 

Panes are the most important kinds of views. All drawing takes place in a 
pane. The THINK Class Library defines different kinds of panes designed for 
different kinds of displays. Every pane has its own drawing environment, so 
you can draw in a pane without worrying about where it is on the screen. 

Visual events work their way down the visual hierarchy. Since Macintosh 
update and activate events always have a window associated with them, 
these messages get sent directly to a window object. Mouse clicks and cursor 
adjustment messages always work their way down from the desktop to the 
active window to the appropriate pane. 


i 
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Panes can handle visual commands like mouse clicks. When you click in a 
pane, the switchboard determines which pane the mouse went down in and 
sends itaDoClick message. Because they’re descendants of CBureaucrat, 
panes can be in the chain of command and respond to direct commands. 

The chain of command 

The chain of command specifies which object handles a direct command. 
The chain of command is based on the idea of supervisors and bureau¬ 
crats. Every object in the chain of command is a bureaucrat. If a bureaucrat 
can’t handle a direct command, it passes the command on to its supervisor. 
The application is the only bureaucrat that does not have a supervisor. If the 
application doesn’t handle the command, no object will. 

Objects in the chain of command are descendants of the class CBureaucrat. 
Every bureaucrat has a DoCommand method that the subclass can override 
to handle specific commands. The default DoCommand method just sends a 
DoCommand to its supervisor. 

The first object to get a chance to handle a command is called the gopher. If 
the object that the gopher points to can’t handle the command, it sends the 
command on to its supervisor. Your application is responsible for sending a 
BecomeGopher message to a bureaucrat that should be the gopher. 

In Figure 7-3, the gopher points to a pane whose supervisor is a document. 
If the pane can’t handle a direct command, it passes the command on to the 
document. If the document can’t handle the command, it gets passed up to 
the application. 

The Chain of Command The Visual Hierarchy 



Figure 7-3 The gopher, the chain of command, and the visual hierachy 
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The enclosures in the visual hierarchy are drawn in gray. Note that the chain 
of command is separate from the visual hierarchy. 

CDirector is an important subclass of CBureaucrat that you need to know 
about. A director is a bureaucrat that supervises a window. Directors handle 
the communication between the visual hierarchy and the chain of com¬ 
mand. For instance, when a window gets an activate event, it sends an 
ActivateWind message to its supervisor, which is always a director. The 
director can then take some action as a result of becoming active. 

Another descendant of CBureaucrat is CDocumenL A document is a director 
that has a file associated with it Documents manage the communication be¬ 
tween windows, files, and menu commands. The default document class 
handles common commands like Save, Save As..., Print, etc. You can think 
of a document as a file that you view through a window. A better way to 
think about a document is that it is the essence of a Macintosh application. It 
is anything that you can display and manipulate inside a window. 

Every bureaucrat is a descendant of the class CCollaborator. A collaborator 
is an object that can let other objects know that something has happened. 
One collaborator is called the provider, and another is called the depen¬ 
dent. For instance, a provider might be a document that displays data in sev¬ 
eral windows. Its dependents might be the windows. If the data changes, the 
provider lets the dependents know, so the windows redisplay the data cor- 
rrectly. 

The flow of control 

The chain of command and the visual hierarchy get their direction from the 
switchboard. The switchboard gets events from the Macintosh Event Manag¬ 
er and converts the event into messages for either the chain of command or 
the visual hierarchy. Messages for the chain of command usually go to the 
gopher, the first bureaucrat in the chain. Messages for the visual hierarchy go 
to the active window or to the desktop. 

When you press the mouse, the switchboard sends a DispatchClick 
message to the desktop. If the click was in the menu bar, the desktop sends 
the bartender a message to update the state of the menus before they ap¬ 
pear. The bartender sends a message to the chain of command to enable and 
disable the appropriate menu items. Then the desktop uses the bartender to 
convert the menu selection into a direct command and sends a DoCommand 
message to the gopher. 

If the click was in a window, the desktop sends a DispatchClick mes¬ 
sage to the window, which eventually sends a DoClick message to the 
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pane the mouse went down in. The pane’s DoClick method can then do 
whatever’s appropriate for the pane. It might even send a Do Command mes¬ 
sage to an object in the chain of command. 

When the switchboard gets an activate or an update event, it sends an 
Activate, Deactivate, or Update message to the window. The win¬ 
dow sends a similar message to its director. 

When you type, the switchboard sends a DoKeyDown or a DoAutoKey 
message to the gopher. If you hold down the Command key when you type, 
the switchboard asks the bartender to convert the key into a command and 
sends a DoCommand message to the gopher. 

If you’re running under MultiFinder, and you bring another application to 
the foreground, the switchboard sends a Suspend message to the applica¬ 
tion (not the gopher) which sends Suspend messages to all of its directors. 
A similar thing happens when your application comes to the foreground. 


Note 

The THINK Class Library treats desk accessories as if they 
were in their own layer, even if you’re not using MultiFind¬ 
er, so your application will still get suspend and resume 
“events” when you bring up a desk accessory. 


Writing an Application with the TCL 

This section tells you how to write an application with the THINK Class Li¬ 
brary. The easiest way to do this, is to take the Starter program and build 
from it. 

To create an application with the THINK Class Library, you create subclasses 
of existing classes. The three classes you need to override are CApplication, 
CDocument, and CPane. Your application subclass determines the overall 
structure of your application. The document subclass implements the way 
your application handles its files, and the pane subclass implements how the 
information in your file appears in the document windows. 

In addition to the subclasses, you also need a resource file for your project. 
This resource file must contain the standard THINK Class Library resources 
as well as your own. The standard THINK Class Library resources are in the 
file TCL Resources. When you use the THINK Class Library, make a 
copy of this resource file and name it the same as your project and append 
. rsrc to it. Then add your own resources to it. 
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Note 

For more information about resource files and the THINK 
Class Library, see “THINK Class Library Resources” on page 
96. To learn about using resources with a project, see Chap¬ 
ter 7, “The Project,” of the THINK C User Manual or Chap¬ 
ter 7 “Working with Projects” in the THINK Pascal User 
Manual 


Creating the project In THINK Pascal 

Use the Starter project as the beginning of your project. The Starter project is 
in the Starter Folder in the TCL 1.1 Demos Folder. 

1. Copy the Starter Folder and change its name to the name 
of your application 

2. Open the new folder 

3. Rename Starter. tc to the name of your application 

4. Rename Starter. Build.TC to the nameof your application, but keep 
the .Build.TC suffix. 

5. Rename Starter. tc. rsrc to the name of your project plus 
. rsrc 

6. Open the project without the .Build.TC suffix. 

7. Use the Run Options... dialog to choose the resource file you 
renamed in step 5. 

8. Use the Find... command in the Search menu to change 
Starter to the name of your application 

9. Use the Save As... command to save the files under your own 
names (the Save As... command also changes the names of the 
files in the project) 

THINK Pascal uses two projects—one for debugging and one for building 
the final application. When you build an application, THINK Pascal has to 
turn the debugging options off. That means that the entire THINK Class Li¬ 
brary would need to be recompiled. By using two projects and switching to 
the . Build, tc project when you want to build the final application, only 
your own files will need to be recompiled. 
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Creating the project in THINK C 

Use the Starter project as the beginning of your project. The Starter project is 
in the Starter Folder in the TCL 1.1 Demos Folder. 

1. Copy the Starter Folder and change its name to the name 
of your application 

2. Open the new folder 

3. Rename Starter. n to the name of your application 

4. Rename Starter .n. rsrc to the name of your project plus 
. rsrc 

5. Open the project 

6. Use the Find... command in the Search menu to change 
Starter to the name of your application 

7. Use the Save As... command to save the files under your own 
names (the Save As... command also changes the names of the 
files in the project) 

Use the Set Project Type... dialog to make sure that your project is Multi- 
Finder Aware and will receive Suspend & Resume events. 

Creating the application subclass 

If your application is a standard Macintosh application, your application 
subclass must override these methods: 

Initialization method 

SetUpFileParameters CreateDocument 

OpenDocument DoCommand 

Your initialization method should initialize any instance variables that your 
subclass declares. It must call CApplication’s I Application method. 

The SetUpFileParameters method sets up the standard file parameters 
that specify which files are visible in the standard file box when the user 
chooses Open... from the File menu. 

The CreateDocument method creates a new, untitled document. The doc¬ 
ument it creates is one that you define as a subclass of CDocument. After 
creating the document, your CreateDocument method should send it a 
NewFile message. This is the method that gets called when the user choos¬ 
es New from the File menu. 

The OpenDocument method is like the CreateDocument method. In¬ 
stead of sending the newly created document a NewFile message, though, 
this document should send it an OpenFile message. The OpenDocument 
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method takes one parameter, an SFReply record, that contains the informa¬ 
tion about the file that the user chose to open. 

The DoCommand method handles all the application-specific commands. 
Most of the commands should be handled at the document level. Some com¬ 
mands, like New, Open, and Quit, are handled by the default application 
class. 

Creating the document subclass 

The document is where your application draws and displays its data. All 
documents have windows associated with them. Most documents also have 
an associated file. Neither the window nor the file are created automatically. 
You must create them yourself. 

Your document class should override these methods: 

Initialization method OpenF i 1 e 

Dispose DoSave 

DoCommand DoSaveAs 

NewFile Revert 

Your document class must have an initialization method. If your subclass de¬ 
fines new instance variables, this is the method that sets them up. By con¬ 
vention, the name of your initialization method should be I YourDoc where 
YourDoc is the name of your document class. Your initialization method 
should call the inherited method. The supervisor of a document is always 
gApplication. 

If your document allocates memory, you should also override the Dispose 
method to deallocate it. Be sure that your method calls 
inherited: :Dispose (inherited Free in Pascal) to make sure that 
the document is disposed of properly. 


Note 

You do not need to dispose of the it sWindow or the 
itsFile instance variables. The default Dispose or 
Free method does that for you. 


Your document class’s DoCommand method does most of the work in your 
application. When a window is active, the switchboard will send all com¬ 
mands to the document first (it’s the gopher), and if the document can’t han¬ 
dle it, the application class tries to handle it. Your document class should 
handle all the commands it knows about, and call the inherited method 
when it can’t. 
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Note 

Be sure that your DoCommand method or that one of the 
methods it invokes sets the instance variable di rty to 
TRUE when there has been a change to the document. 


Your document class will get a NewFile message when the user chooses 
New from the File menu. This method needs to create a window and attach 
the panes for it. The NewFile method doesn’t need to create a file until the 
user tries to save the document. 

Your document gets an OpenFile message when the user chooses Open... 
from the File menu. The OpenFile method has one argument: a pointer to 
a Macintosh SFReply record. When you get the OpenFile message, you 
can be sure that the SFReply record is properly filled in. Your OpenFile 
message needs to create an instance of a file object (usually of class CData- 
File). You can send your file any of several read messages to obtain its con¬ 
tents. Your OpenFile method also needs to create a window to display the 
contents of the file, just as your NewFile method does. 

When the user chooses Save from the File menu, your document gets a 
Do Save message. Your DoSave method should write the contents of its file 
to disk. The file object is stored in the instance variable itsFile. 

When the user chooses Save As... from the File menu, your document gets 
a DoSaveAs message. This method takes an SFReply record, and you can 
be sure that it is properly filled in. Your document class needs to override 
this method to write its data to a file. 

If your application supports the Revert command, you should implement it 
in the DoRevert method. Your implementation might do the same thing as 
closing without saving, then opening the file again. 

Creating the pane subclass 

Once you’ve created your windows and opened your files, you need to dis¬ 
play them somewhere. In the THINK Class Library, you don’t write directly 
onto the window. Instead, you create a subclass of class pane. 

When you create a subclass of Pane, you need to override these methods: 

I YourPane Dispose 

Draw DoClick 

Your pane class should have an initialization method. If your subclass de¬ 
fines new instance variables, this is the method that sets them up. By con- 
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vention, the name of your initialization method should be I Your Pane where 
YourPane is the name of your pane class. Your initialization method should 
call the inherited method of whatever pane class you’re overriding. The su¬ 
pervisor of a pane should be either the pane that encloses it or the director 
its window belongs to. 

The pane initialization method is where you set the pane’s location in its en¬ 
closure and its characteristics. If you want your pane to receive clicks, be 
sure to send the pane a SetWantsClicks (TRUE) message, otherwise 
mouse clicks in your pane are ignored. 

If your pane allocates memory, you should also override the Dispose or 
Free method to deallocate it. Be sure that your method calls inherited meth¬ 
od to make sure that the pane is disposed of properly. 

The Draw message tells your pane to draw its contents. You can assume that 
the port, clip region, and coordinate system have been set up correctly. See- 
section “Drawing in a pane” on page 80 to learn all about drawing in a pane. 

When you click in a pane, it will get a DoClick message. Your DoClick 
method can handle the mouse click itself to draw something, to drag an ob¬ 
ject, or to select something. Some panes, like the edit text pane implemented 
by CEditText, have built-in DoClick methods. 

If you want your mouse action to be undoable, you need to create a subclass 
of CMouseTask and send it in a TrackMouse message. The section “Mouse 
tracking” on page 94 goes into more detail about undoable mouse actions. 

Working with Panes 

In the THINK Class Library, all your drawing takes place in a pane. A pane is 
a rectangular region of the screen completely enclosed by a window. A win¬ 
dow may have several panes, and each pane may have several subpanes. 
Each pane has its own drawing environment and can handle its own visual 
commands. 

Every pane has an enclosure that completely encloses the pane. A pane 
also has a supervisor—an object in the chain of command. A pane’s enclo¬ 
sure and supervisor can be the same object, particularly if the pane belongs 
to another pane. In most the common case, though, the supervisor is the di¬ 
rector that owns the window or the pane. 

Every pane has its own drawing environment. The rectangle that describes 
the edges of a pane is the frame. The frame defines a local coordinate sys- 
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CPicture 


CCheckBox 
CEditText - 


tem for the pane. In most cases, the top, left corner of the pane is the point 

( 0 , 0 ). 


Windows and panes 

All panes are subclasses of the abstract class CView which defines the be¬ 
havior of visual entities. A window is a view, but it is not a pane. Other visu¬ 
al entities are subclasses of panes; they include things like controls, borders, 
pictures, and size boxes. 


Every pane belongs to a window or to another pane. The outer, or owning 
pane, is the enclosure. Every pane has one enclosure. For example, in the 
window in Figure 7-4, there are seven panes (the window is not a pane): 



CScrollPane 


CScrollBar 


CSizeBox 


Figure 7-4 The panes in a window 


The size box, the check box, the text, and the scroll pane are enclosed by 
the window. The two scroll bars belong to the scroll pane. The picture is en¬ 
closed by the window. 
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Coordinate systems 

When you’re working with panes in the THINK Class Library, you need to 
know about four coordinate systems: 

• Global coordinates 

• Window coordinates 

• Frame coordinates 

• QuickDraw coordinates 

The desktop, some internal methods, and some Toolbox routines use global 
coordinates. In this coordinate system, all units are in pixels, and (0, 0) is at 
the top, left corner of the main screen. You rarely use global coordinate in 
the THINK Class Library. 

In window coordinates the top, left comer of the window’s content region 
is (0, 0) and each unit is a pixel. The only time you need to use window co¬ 
ordinates is to set the position of a pane whose enclosure is a window. Win¬ 
dow coordinates are also useful as a common point of reference for two 
different panes in the same window. 

Frame coordinates provide a local coordinate system for a pane. Units in 
frame coordinates are in pixels, and the point (0, 0) is usually the top left 
corner of the pane. If the pane moves within its enclosure, the coordinate 
system does not change; the top left corner is still (0, 0). The only time this 
origin point changes is when you scroll the pane. Each pane can choose to 
use long coordinates or short coordinates. 

All drawing and mouse tracking is done in QuickDraw coordinates. This 
is the coordinate system that the Macintosh Toolbox uses for its drawing op¬ 
erations. QuickDraw coordinates are only valid after a call to Prepare.The 
relationship between QuickDraw coordinates and the other coordinate sys¬ 
tems depends on whether a pane is using long frame coordinates or short 
frame coordinates. 

Short coordinates map directly to QuickDraw coordinates. Each element 
in a short coordinate uses l6-bit values, so a pane that uses short coordinates 
is limited to the rectangle (-32768, -32768, 32767, 32767). Long coordi¬ 
nates layer a 32-bit coordinate system on top of the QuickDraw 1 6 -bit coor¬ 
dinates. The long coordinate system lets you use a much larger coordinate 
area for your pane. Since all drawing takes place in QuickDraw coordinates 
you have to map the long coordinates to QuickDraw coordinates when you 
draw in a pane. 
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The CPane class defines several methods that transform coordinates from 
one system to another. 

Drawing in a pane 

Every pane has its own drawing environment. The rectangle that describes 
the edges of a pane is the pane’s frame. The frame defines a local coordi¬ 
nate system for the pane. In most cases, the top, left corner of the pane is the 
point (0, 0). 

To draw in a pane, you override its Draw method. The THINK Class Library 
sends your pane a Draw message whenever the pane needs to be updated. 
You can send a Ref res h message yourself if you want to force an update 
event. 

To draw in a pane use the standard QuickDraw routines. The pane’s 
Prepare method sets up the QuickDraw port. If your pane uses short coor¬ 
dinates, you the coordinate system is set up correctly. If your pane uses long 
coordinates, you need to transform frame coordinates to QuickDraw coordi¬ 
nates before you draw. You can CPane methods FrameToQD and Frame- 
ToQDR convert frame points and rectangles to QuickDraw points and 
rectangles. 

The THINK Class Library uses the types LongRect and LongPt for both 
long and short corrdinates. You’ll notice that most of the descendants of 
CView that work with points and rectangles use these types. 


Note 

If you’ve worked with earlier versions of the THINK Class 
Library, this is the biggest change you’ll notice since it will 
require some changes to your programs. 


These two types are defined like this in LongCoordinates . h in C: 

typedef struct LongPt 
{ 

long v, h; 

} LongPt; 

typedef struct LongRect 
{ 

long top, left, bottom, right; 

} LongRect; 
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And like this in TCL . p in Pascal: 
type 

LongPt = record 

case integer of 
1 : ( 

v, h: longint 
); 

2 : ( 

vh: array[VHSelect] of longint 
) ; 

end; 

LongRect = record 

case integer of 
1 : ( 

top, left, 

bottom, right: longint 
); 

2 : ( 

topLeft: LongPt; 
botRight: LongPt 
) ; 

end; 

If the pane uses short coordinates, frame coordinates and QuickDraw coord- 
iantes are identical, so the values stored in a LongRect or in a LongPt are 
in QuickDraw coordinates. To use them with QuickDraw routines, however, 
you’ll need to convert them to the QuickDraw types Rect and Point. The 
THINK Class Library provides several utility routines to do these conver¬ 
sions. For a complete list, see “Long Coordinate Utilities” on page 462. 

To draw directly in a pane as a result of a mouse click, you need to override 
the DoClick method of the pane. Just as in drawing, if your pane uses short 
coordinates, you do not need to transform frame coordinates to QuickDraw 
coordinates. If you use long coordinates, you must transform the coordi¬ 
nates before you draw. To make your mouse action undoable, use a mouse 
task. See the section “Undoing and Mouse Tracking” on page 93. 

Properties of panes 

When a pane moves or changes size, all of the panes that it encloses change 
as well. The way a pane changes depends on its sizing characteristics. 
When you create a pane, you specify its horizontal and vertical sizing char¬ 
acteristics. 
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The horizontal sizing characteristic specifies how the pane’s left and right 
edges change. 

Horizontal sizing Meaning 

sizFIXEDLEFT The left edge of the pane is always the 

same number of pixels from the left edge 
of the enclosing pane as when it was orig¬ 
inally placed. 

sizFIXEDRIGHT The right edge of the pane is always the 

same number of pixels from the right edge 
of the enclosing pane as when it was orig¬ 
inally placed. 

si z FIXED STICKY The left and right edges stick to their origi¬ 

nal locations in the enclosing pane. If the 
enclosure scrolls horizontally, the pane 
will scroll with it. 

sizELASTIC The width of the pane grows or shrinks by 

the same amount as the width of the en¬ 
closing pane. 

The vertical sizing characteristic specifies how the pane’s top and bottom 
edges change. 

Vertical sizing Meaning 

sizFIXEDTOP The top edge of the pane is always the 

same number of pixels from the top edge 
of the enclosing pane as when it was orig¬ 
inally placed. 

sizFIXEDBOTTOM The bottom edge of the pane is always 

the same number of pixels from the bot¬ 
tom edge of the enclosing pane as when it 
was originally placed. 

sizFIXEDSTICKY The top and bottom edges stick to their 

original locations in the enclosing pane. If 
the enclosure scrolls vertically, the pane 
will scroll with it. 

sizELASTIC The height of the pane grows or shrinks 

by the same amount as the height of the 
enclosing pane. 

A couple of examples might help: A vertical scroll bar in a window has the 
characteristics sizFIXEDRIGHT and sizELASTIC. It has a fixed horizon¬ 
tal length and remains anchored to the right edge of the window. Vertically, 
it changes with the height of the window. A status box in the lower left cor- 
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ner of a window would be sizFIXEDLEFT horizontally and 
si zFIXEDBOTTOM vertically. It has a constant size and remains anchored to 
the bottom left corner of the window. 

In Figure 7-5, the dark line represents the window. It contains a main pane 
that takes up most of the window and several other panes. The two panes 
that hold the scroll bars are fixed to the edges of the window. When the win¬ 
dow is resized, they grow or shrink by the same amount as the window. The 
panes that hold the grow box and the status box are anchored to the bottom 
corners of the window. The square pane in the upper left portion of the 
main pane will always be there, regardless of how the window changes. Its 
dimensions will not change automatically. 

H: sizELASTIC 



Panoramas 

Almost everything you want to display is bigger than a pane. Graphics and 
text, for instance, frequently take up more room than what you can fit in a 
pane. The THINK Class Library provides a panorama class, CPanorama, 
that lets you display portions of a large graphic in a pane. You might say a 
panorama is a pane that scrolls. 
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Think of a panorama as a sheet of paper glued to a desk. The frame moves 
over the paper. The only part of the panorama you can see is what’s inside 
the frame. To scroll, you move the frame around on the panorama to see dif¬ 
ferent parts of it. 

The rectangle that completely encloses the panorama is called the bounds 
rectangle. The bounds rectangle defines the size and coordinate system of 
the panorama. Usually, the top, left comer of the bounds rectangle is the 
point (0, 0), and the units in its coordinate system are pixels. 

The coordinate system of the bounds rectangle specifies how the frame 
moves over the panorama when you scroll. In the usual case, when you 
scroll up, you move the pane up a pixel. In some applications, though, you 
want to scroll more than one pixel. In a text editing application or in a 
spreadsheet application, you want to move up by an entire line. 

You can specify a scale that says how many pixels make up a single panora¬ 
ma unit. You can set different scales for horizontal and for vertical units. In a 
graphics application, each unit might be one pixel. In a spreadsheet, a verti¬ 
cal unit might be 12 pixels, and a horizontal unit might be 60 pixels. 

The units of the panorama bounds are for scrolling only. For drawing, you’ll 
use the frame coordinates which are always pixel units. 

There are two ways to talk about the top, left corner of the frame of the 
pane. The top, left corner of the pane, expressed in panorama units, is the 
position of the frame in the panorama. The top, left corner, expressed in 
frame coordinates, is the origin of the frame. 

The key thing to remember is that scrolling always happens in panorama 
units. Drawing always takes place in frame coordinates. As you scroll, the 
origin of the frame changes. A couple of examples might help. 

In Figure 7-6, both the horizontal and vertical scales are set to 1 pixel per 
panorama unit. The bounds rectangle of the panorama is (0, 0, 400, 380). 
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The portion of the picture you can see in the frame of the pane, the fish’s 
tail, starts at (165, 210) in the panorama. 



Since the panorama units match the frame units, the position of the frame in 
the panorama and the origin of the frame are the same. If you were to draw 
a line from (220, 230) to (270,230), it would cut across the tail of the fish. 

In Figure 7-7, which shows a panorama with text, the horizontal scale is 6 
pixels per unit, and the vertical scale is 12 pixels per unit. The bounds rect¬ 
angle of the panorama is (0, 0, 40, 9). In the panorama scale, this means 8 
lines of 40 characters each. The position of the frame in the panorama is (0, 
3), the beginning of the fourth line. The origin of the frame, however, is at 
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(0, 36). If you wanted to draw a line to strike out the word “And,” you would 
draw it from (0, 42) to (18, 42) 

bounds frame 

( 0 , 0 )_ I _ j_ 

'Twas brillig and the slithy toves 

Did gyre and gimble through the webe:- panorama 

position (0. 3) All mimsey were the borogovej), _ 

origin (0.36) And the mome raths outgrabe. 

"Beware the Jabberwock, my son. 

The jaws that bite, the claws that catch 
Beware the Jubjub bird and shun 
the frumious Bandersnatch!" 

(40.9) 

Figure 7-7 A text panorama and its scales 


Note 

The top, left of the bounds rectangle doesn’t have to be (0, 

0). You can define the bounds coordinate system that’s 
most convenient for the kind of data you’re displaying in 
the panorama. 

Scroll panes 

To make it easy to use panoramas, the THINK Class Library provides a class 
called CScrollPane that implements a scroll pane. Scroll panes give you an 
easy way to attach scroll bars to your panorama. 

You create a scroll pane the same way as any other pane. You can request a 
vertical scroll bar, an horizontal scroll bar, and a size box. Then you use the 
InstallPanorama method to associate a panorama with the scroll pane. 
The scroll pane examines the panorama and adjusts the scroll bars appropri¬ 
ately. You can specify how many panorama units to scroll when you click on 
different parts of the scroll bar. 

The scroll bars and the panorama communicate through the scroll pane. 
When you click in one of the scroll bars, it tells the scroll pane which tells 
the panorama how much to scroll. 
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Cursor tracking 

The Ad just Cursor method that all panes inherit from CView lets you 
change the cursor when it moves into your pane. Most of the time you’ll use 
only one cursor in the whole pane. In this case, all you have to do is set the 
cursor with the Toolbox routine SetCursor. Look at the Ad justCursor 
method in CEditText for an example. 

Sometimes, though, you might want to use different cursors within the same 
pane. The Ad just Cursor method lets you do this as well, but it takes a lit¬ 
tle more work. See the description of the CView class in Chapter 52. 

Initializing views from resources 

The IViewRes method lets you initialize any descendant of CView from a 
resource template. 

Resource Class 

Pane CPane 

Pano CPanorama 

PctP CPicture 

ScPn CScrollPane 

AbTx CAbstractText, CEditText 

View CView 

You can use ResEdit to create the resource templates for each class. 


Note 

Your THINK C package includes a file TCL TMPLs that 
contains TMPL resources you can install into ResEdit. These 
TMPLs let you create and edit the resources above. See the 
instructions in Chapter 2, “Installing the THINK Class Li¬ 
brary,” to learn how to install these TMPLs into ResEdit. 


When you use ResEdit to create view resource templates, keep in mind 
these values for sizing and clipping mnemonics. 


Sizing values 

sizFIXEDLEFT = 0 
sizFIXEDRIGHT = 1 
sizFIXEDTOP = 2 
sizFIXEDBOTTOM = 3 
sizFIXEDSTICKY = 4 
sizELASTIC = 5 


Clipping values 

clipAPERTURE = 0 
ClipFRAME = 1 
clipPAGE = 2 
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Working with Menus 

The THINK Class Library lets you think of your menu commands more ab¬ 
stractly than the Macintosh Toolbox. Instead of identifying a menu com¬ 
mand by its menu ID and item number, the THINK Class Library lets you 
assign unique command numbers to each item of the menu. With com¬ 
mand numbers, you can reassign functions to different menu items without 
having to rebuild the application. 

Command numbers are positive long integers in the range 1 to 
2,147,483,647. Command numbers in the range 1 to 1023 are reserved for 
the THINK Class Library. Command number 0 is reserved for cmdNull, the 
null command. All other command numbers (1024 to 2,147,483,647) are 
available for your application. 

The reserved commands are for the most common Macintosh application 
commands like Open, Save, Quit, Page Setup..., etc. Be sure you use the 
reserved command number if you expect to get the default behavior from 
the THINK Class Library. For a list of all the reserved commands see the de¬ 
scription for CBartender on page 165. 

When you choose a command from the menu bar, the desktop sends a 
FindCmdNumber message to the bartender. The bartender matches the 
menu ID and the item number to a command number and sends it to the go¬ 
pher in a DoCoromand message. If the you use a Command key equivalent, 
the switchboard sends the DoCommand message to the gopher. 


Note 

Remember, the gopher is a pointer to a command object. 
Usually, the gopher points to a pane in the active window. 
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Using MENU resources 

When you create your menus with ResEdit, append the command number 
to the menu item. The menu item and the command number are separated 
by the character #. For example, Figure 7-8 shows the File menu. 


IO 


MENU “File” ID = 2 from TCL Resources 


File 


New#2 

Open. ..#3 

§§N 

a 

■ 

J88 

Close#4 

HID 

jjijj! 

iiiiii 

Saue^S 

xs 


Saue Rs...#6 



Reuert to Saued#7 

... 

ijijrj 

ill 

Page Setup...#8 

ii! 

Print... #9 

8§P 

rat 


£2 


Entire Menu: 


H Enabled 


Title: <$ 


File 


O 6 (Rpple menu) 


Color 

Title: 

Item TeHt Default: 

Menu Background: 



Figure 7-8 The File menu in ResEdit 


Note 

If you don’t append a command number to a menu item, 
the bartender automatically assigns it cmdNull. 


The MENU resources for 
these menus are in the file 
TCL Resources. 


You can use any menu ID for your application’s menus. The THINK Class Li¬ 
brary reserves the following menu IDs for certain menus: 


Menu title 

Apple 

File 

Edit 

Font 

Size 


Menu ID 

1 

2 

3 

10 

11 


Mnemonic 

MENUapple 

MENUfile 

MENUedit 

MENUfont 

MENUsize 


After you create all the menus that your application needs, create an 
MBAR 1 resource that contains all of the IDs of the menus your application 
uses. The application’s SetUpMenus message creates the bartender (stored 
in the global variable gBartender) to read the MBAR 1 resource. The 
bartender creates the tables that match command numbers to menu items. 
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Note 

Your application’s menus must be in MBAR 1 unless you 
change the defnition of MBARapp in Constants . h. or 
TCL.p. 


If you want the bartender to return the menu ID and item number of a par¬ 
ticular menu item, use the special command number -1 in your MENU re¬ 
source. The bartender will return the negative of the menu ID in the high 
word and the menu item number in the low word. This is the same as menus 
that you build on the fly, described next. 

Building menus on the fly 

Menus that you create as your program is running, like Font menus, won’t 
have command numbers associated with them. In this case, the bartender’s 
FindCmdNumber method returns the negative of the menu ID in the high 
word and the item ID in the low word. When your DoCommand method gets 
a negative command number, you know you have to figure out the com¬ 
mand from the menu ID and item number. 


For example, if DoCommand gets a command -655369 (0xFFF5FFF7), it 
means that there is no command number associated with the menu item. To 
get the menu ID and the menu item, negate the value and split it into two 
words. In this example, the return value becomes 655369 (0x000A0009), 
which means that the menu ID is 10 and the menu item is 9. 


menuID 


menultem 


Figure 7-9 How FindCmdNumber builds command numbers. 


You can add menu items to existing menus if you like. For example, you 
might want to add the Font menu to a general text-handling menu, or you 
might want to have a menu with the names of all the documents your appli¬ 
cation has opened. The important thing to remember is to add all these 
menus at the end of the existing menu. Otherwise, the bartender will get 
confused. 

Dimming and checking menu items 

The bartender includes methods to let you enable and disable and check 
and uncheck menu items. When you click in the menu bar, the bartender 
sends an UpdateMenus message to all of the bureaucrats in the chain of 
command. In the general case, all the items in the menu start out dimmed 
and unchecked. Then each bureaucrat enables the menu items that pertain 
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to it. Once the appropriate items have been enabled and checked, the Tool¬ 
box routine MenuSelect displays all the menus. 

Note 

The dimming, undimming, and unchecking take very little 
time. You won’t notice a delay between the time you click 
on the menu bar and when the menu is displayed. 

Suppose you click in the menu bar of a text processing application. When 
you click on the menu bar, but before the Toolbox displays the menu, the 
bartender disables all the menu items. Then, the application enables all the 
application related menu items: New, Open..., Quit, for example. The doc¬ 
ument enables all the document related items: Save, Save As..., Revert (if 
the document’s been changed), and so on. A pane might check the current 
font and size in the Font menu. Finally the menu appears on the screen with 
the correct items checked and enabled. 

The UpdateMenus method of your application, document, and pane need 
to enable each item. To make sure that item enabling happens from the gen¬ 
eral (application) to the specific (pane), be sure to call the inherited method 
first in your own UpdateMenus method. 

You can use the bureaucrat methods SetDimOption and 
SetUnchecking in your application SetUpMenus method to modify this 
behavior. SetDimOption lets you specify whether the bartender should 
dim all, some, or none of the items when you click on the menu bar. For 
Font menus, for instance, it doesn’t make sense to dim all the font names 
only to reenable them again. 

Dim Option Meaning 

dimNONE Never dim any of the menu items. 

dimSOME Dim only the menu items that have com¬ 

mand numbers associated with them. 
dimALL Dim all of the menu items. Each bureau¬ 

crat’s UpdateMenus method must enable 
the items for the commands it handles. 

This is the default. 
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There are only two options for SetUnchecking. The bartender either 
unchecks all the items or it doesn’t. 


Unchecking option Meaning 

TRUE Uncheck all the menu items at menu se¬ 

lection. Your UpdateMenus method 
should check the appropriate items. Set 
this option for menus like Font menus or 
Style menus. 

FALSE Don’t uncheck any menu items at menu 

selection. This is the default since most 
menu items never need to be checked. 


Handling Low Memory Situations 

The term "rainy day fund " The CApplication class provides several methods that deal with low memory 
comes from the expression situations. These methods use a memory reserve called the rainy day fund. 
"saving for a rainy day ." It 

means to save money in —- 

case of disaster. Note 

For details about the methods and instance variables de¬ 
scribed in this section, see Chapter 11, “CApplication.” 


When you call I Application, you specif/ how much memory your appli¬ 
cation should allocate for the rainy day fund. You also specify how many 
bytes of that fund should be available to satisfy Toolbox routine memory re¬ 
quests and how many bytes of that fund should be available to satisfy critical 
operation requests. These values are stored in the instance variables tool- 
boxBalance and criticalBalance. 

If the Macintosh Memory Manager gets a request for more memory than is 
available, it calls a grow zone function. In the THINK Class Library, the grow 
zone function sends the application a GrowMemory message. 

The GrowMemory method tries several strategies to free memory in the 
heap. First, it sends the application a MemoryShortage message. Your ap¬ 
plication subclass should override this method to release memory that is not 
crucial to execution. For instance, your MemoryShortage method might 
might dispose of a buffer it no longer needs. If the MemoryShortage 
method wasn’t able to release enough memory, GrowMemory starts using 
the rainy day fund. 

GrowMemory looks first at the inCriticalOperation instance variable 
to relase memory from the rainy day fund: 
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If inCriticalOperadon Is leave this much in reserve 

TRUE toolboxBalance 

FALSE criticalBalance 

A critical operation is a temporary operation that takes place in a single Mac¬ 
intosh event, that might take a lot of memory, and that should never fail. For 
instance, saving a file is a critical operation. You can use the routine Set- 
CriticalOperation to set the inCriticalOperation flag. 

If GrowMemory still wasn’t able to release enough memory and the canFail 
flag is TRUE, GrowMemory returns without trying to allocate any more 
memory. If the canFail flag is TRUE, the application is saying that it can 
deal with a failing memory request. 

If the canFail flag is FALSE, GrowMemory tries to release all the memory 
left in the rainy day fund because the application is not prepared to deal 
with a failing memory request. If there is not enough memory, even after us¬ 
ing the rainy day fund, it is likely that the application will crash. 

You can use the routine SetAllocation to set and reset the canFail 
flag. In general, your application should be prepared to handle failing mem¬ 
ory requests. 

Undoing and Mouse Tracking 

The THINK Class Library provides a class that lets you implement the Undo 
command easily. In the default implementation, each document has its own 
undo history. 

Undoing 

The THINK Class Library uses the abstract class CTask to implement undo- 
able actions. For every undoable action you want in your application, you 
need to create a subclass of CTask. 

After you perform an action, you store enough information to undo it in 
your task’s instance variables. Then you send the task to your supervisor in a 
Notify command. The CDocument class implements the Notify method 
to store a task in one of the document’s instance variables. When you 
choose Undo from the Edit menu, the document’s DoCommand method 
sends an Undo message to the task it stored. 

Here’s an example. Suppose you’ve defined a subclass of CTask to change 
the font in an edit text pane. Before passing the command on to the edit 
pane’s DoCommand method, you create a task and store the current font in 
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an instance variable. After you pass the font command to the edit text pane, 
you send the task in a Notify message to the document. 

Your Undo method would simply send the font change command to the 
document. Since the command goes through the regular command chain, 
your DoCommand method would create a task to let you undo what you 
were undoing. 

Mouse tracking 

The THINK Class Library uses the undo mechanism to make mouse tracking 
easier and undoable. The CMouseTask class is an abstract class that defines 
some methods specifically for mouse tracking. 

To implement a mouse tracking task, define a subclass of CMouseTask and 
override the KeepTracking and EndTracking methods. The Keep- 
Tracking method does whatever you want to happen while the mouse is 
down. The EndT racking method does whatever you want to happen 
when the mouse is released. 

For example, if you’re moving a rectangle from one place in a pane to anoth¬ 
er, the KeepTracking method might draw a gray outline that moves as 
you move the mouse. The EndTracking method would erase the rectan¬ 
gle from its old location and redraw it in the new location. 

If you want to make your mouse task undoable, you need to store enough 
information in the object to undo the effects of mouse tracking. You must 
also override the Undo method (inherited from CTask) to use this informa¬ 
tion to undo the effects of the mouse task. 

After tracking the mouse, you can send the task in a Noti f y message to the 
document. When you choose Undo from the Edit menu, the document 
sends an Undo message to the task to undo the effects of mouse tracking. 

Segmentation and the THINK Class Library 

You can segment your application any way you want. The only thing to 
keep in mind is that certain files and libraries must be in a resident segment, 
that is, a segment that is never purged. 
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THINK Pascal User Manual 
for more information 
about segmentation in 
THINK Pascal. 


Debugging and the THINK Class Library 


In THINK C, these files must be in a resident segment: 

• MacTraps 

• MacTraps2 

• oops (or oopsDebug) 

• TCLUtilities.c 

• LongCoordinates.c 

• Exceptions.c 

In THINK Pascal the following files must be in a resident segment. You can 
set the attributes of their segment to be Locked. 

• TCL.p 

• Exceptions.p 

• TCLRuntime.lib 

• Interface.lib 

• TCL.lib 


Note 

The directive segments «%_MethTables» and «%_Sel- 
Procs» must also be in a resident segment. If you are us¬ 
ing Far Code, «%_MethTables» must be in a segment by 
itself. 


Debugging and the THINK Class Library 

The THINK C and THINK Pascal versions of the THINK Class Library use 
some compiler-specific features to help you debug programs that use the 
TCL. 

Debugging aids In THINK C 

When you’re debugging your application, you should use the library oops¬ 
Debug. This library contains a version of the message dispatcher that checks 
for NULL objects or possibly missing methods. Though there’s no problem in 
building an application with this library, it is slightly less efficient than the 
regular oops library. 

If the preprocessor symbol_TCL_DEBUG_is defined, certain error- 

checking functions like the ASSERT macro are enabled. The ASSERT macro 
takes a Boolean expression as an argument an raises an exception if the as¬ 
sertion is FALSE. 

In THINK C, the global variables gBreakFailure and gAskFailure let 
you examine and simulate exceptions. If gBreakFailure is TRUE, THINK 
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C calls the Toolbox routine Debugger when an exception is raised. If gAsk- 
Failure is TRUE, THINK C calls Debugger when the utility routines like 
FailOSErr that may raise exceptions are called You can then change the 
arguments to the utility routine to simulate an exception. 

There are two underscores at the beginning and end of_TCL_DEBUG_. 

You can set the value of TCL_DEBUG in the Prefix page of the 

Options... dialog. 

Debugging aids in THINK Pascal 

The THINK Pascal version of the THINK Class Library uses three compiler 
variable to control debugging. If the compiler variable TCL_DEBUG is TRUE, 
the Assert procedure is enabled. The Assert procedure evaluates a 
Boolean expression and raises an exception if the result is FALSE. 


Note 

In Starter. it, TCL_DEBUG is set to TRUE. In Start¬ 
er. Build, n it’s set to FALSE. 


If the compiler variable ResumeAf terError is TRUE, any time an excep¬ 
tion is raised, an alert box appears, and the program ends. 

Another compiler variable, DebugExceptions is used only when Re¬ 
sumeAf terError is FALSE. If DebugExceptions is TRUE, the THINK 
Class Library tries to handle exceptions in the THINK Pascal environment. 
The debugging option must be on for any file that may raise an exception. 

If ResumeAf terError is FALSE and DebugExceptions is FALSE, 
theTHINK Class Library handles exceptions in the normal way, but not in the 
THINK Pascal environment. These are the settings in Starter .Build. 71. 

Use the Compile Options... command to set these compiler variables. 

THINK Class Library Resources 

The THINK Class Library requires certain resources in your project’s re¬ 
source file. All of the resources described in this section are in the file TCL 
Resources. The mnemonic constants for all of these resources are in the 
file Constants. h in the Core Headers folder in THINK C and in 
TCL. p in THINK Pascal. 

Alerts 

The ALRT and DITL resources always have matching IDs. You can change 
these resources to suit your application. 
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ALRT/DITL 

Used for 

128 

General. A handy, all-purpose alert box. 

The DITL contains only "*0", so you can 
use the Toolbox routine ParamText to 
set up the text 

150 

Confirm to revert to last saved version. 

151 

Confirm to save changes before closing or 
quitting. 

200 

Severe Macintosh error has occurred. 

250 

No printer selected. 

251 

Error alert. The DITL says “Couldn’t com¬ 
plete the last command because ao.” 

252 

Error alert. The DITL says “Couldn’t suc¬ 
cessfully startup or quit the application be¬ 
cause ao” 

253 

Assertion failed. Used by assertion in ex¬ 
ception handling. 

300 

Macintosh OS error alert. 

Controls 


The THINK Class Library uses this CNTL template for all the scroll bars it ere- 

ates. 


CNTL 

Used for 

300 

Scroll bar 

Error message strings 

The THINK Class Library 

uses a resource of type Estr to report Macintosh 

errors. Estr resources have exactly the same format as STR resources. You 
can use the Res Edit command Open as Template... in the File menu to 
open and edit an Estr resource as a STR . 

The ID of the Estr resource is the error code you want to identify. The file 
TCL Resource includes one Estr. The error handling class CError uses 
Estr resources to display messages. You should create an Estr for every 
error your application reports to the user. 

Estr 

Used for 

-108 

Out of memory 

-192 

Tried to get nonexistent resource 


Menus 

The THINK Class Library reserves these menu IDs for the standard menus. 
The File and Edit menus contain all the standard items. You can remove the 
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ones that don’t apply to your application. The bartender builds the desk ac¬ 
cessory menu for you automatically, but you’ll have to build the Font and 
Size menus yourself in the SetUpMenus method of your application. For 
an example of Font and Size menus, see the TinyEdit project in the TCL 
1.1 Demos folder. 

MENU 
1 
2 
3 
10 
11 

Note 

In THINK C the mnemonics for these menus are in Com¬ 
mands . h, not in Constants . h. In THINK Pascal, these 
constants are in TCL. p. 

Menu bars 

The THINK Class Library uses this resource to install all the menus in your 
application. The MBAR resource in TCL Resources automatically in¬ 
cludes the Apple, File, and Edit menus. 

MBAR Used for 

1 List of all menus to install at application 

startup. 

Small icon 

Earlier versions of THINK Class Library used this small icon to draw a grow 
box instead of the Toolbox routine DrawGrowIcon. If your application 
uses SICNs, you can use the routine DrawSlCN to draw it in a pane. See 
page 459 for details. 

SICN 

200 

Strings and string lists 

The THINK Class library uses these strings for various prompts and messag¬ 
es. You can modify these to suit your application. 


Used for 

Grow box 


Used for 

Apple 

File 

Edit 

Font 

Size 


98 Object-Oriented Programming 



Modifying the THINK Class Library 


♦ 


STR Used for 

150 Prompt for the Save As... dialog box. 

300 Generic operating system error message 
used when noEstr resource is available. 

301 Generic error suffix, “of a Mac OS Error” 

STR# Used for 

128 List of common Macintosh words. This list 
includes the words: quitting, closing, 

Undo, Redo, Untitled, Show Clipboard, 

Hide Clipboard. 

129 Strings used for low memory warnings. 

130 Task names for changing the wording of 
the Undo menu item text. This resource 
has no strings. Your application should 
add strings to this list if it supports Undo. 

See the descriptions of CTask and 
CMouseTask. 

131 Strings used by exception handler. 

Window template 

The THINK Class Library requires only one window template for the Clip¬ 
board window. Your application will probably define one or more addition¬ 
al WIND templates. 

WIND Used for 

200 Clipboard. Window template used for dis¬ 

playing the clipboard. 

Modifying the THINK Class Library 

You can modify the THINK Class Library classes to suit your particular 
needs. To change the behavior of one of the THINK Class Library classes, 
create a new subclass of the class you want to modify, and add new meth¬ 
ods or override the methods you need to change. In some cases, it might be 
a better idea to change the source code for a class. 

Be aware that there are dangers in changing the source code of a class. From 
time to time, Symantec may release new versions of the THINK Class Li¬ 
brary. Changes that you make in the source of a class may make it difficult to 
use new classes or updates of existing classes. If you do make changes to 
the source of a class, be sure to keep an archival copy of the original class 
and to mark your changes clearly. 
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The second danger is a little more subtle. As you use the THINK Class Li¬ 
brary, you may want to create new classes and subclasses to implement 
some kind of behavior. If you want to be able to use these classes in other 
programs, and especially if you want others to be able to use these classes, 
you should not rely on any features of your modified classes. 


Note 

Under your license agreement, you may distribute new 
subclasses of the classes in the THINK Class Library. You 
may not, however, distribute modified sources of the class¬ 
es in the THINK Class Library. 


Where to Go Next 

Learning to use the THINK Class Library takes time and experimentation. 
Start with the Tiny Edit example in the Tiny Edit Folder It was built 
from the Starter application you should use to create your own applications. 
You might start by adding an About... box to the TinyEdit application. 
(Hint: Since it’s an application-wide command, implement it in the applica¬ 
tion’s DoCommand method.) As you explore how the TinyEdit applica¬ 
tion was put together, look at the next chapters to understand how the 
classes of the THINK Class Library work. 
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he THINK Class Library includes a new exception handling mechanism to 
detect and respond to failures. The exception handling mechanism lets you 


divide your routines into two parts: one to handle the normal operation and 
another to handle abnormal situations. 


Note 

Although the exception handling routines are designed to 
work with the THINK Class Library, you can use it in a lim¬ 
ited way with non-TCL programs. 
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What Is an Exception Handler? 

An exception is the occurrence of an abnormal condition during the execu¬ 
tion of a program. For example, your program may open a file, write and 
read data to it, and close it That’s the normal operation for your program. In 
the course of operation, though, your program might encounter several ex¬ 
ceptions: the file may not exist, the file may be unavailable, there might be 
media errors, or your program may not be able to close the file. 

The exception handling mechanism in the THINK Class Library lets you sep¬ 
arate the normal execution part of a routine from the error handling part of 
the routine. Without an exception handler, your program might have this 
kind of structure: 

create a file object 
if creation failed 
report an error 
else 

open the file 
if open failed 

delete the file object 
report an error 
else 

allocate a buffer 
if allocation failed 

delete the file object 
report an error 
else 


As you can see, the normal flow of control is hidden in all the error-checking 
code. With an exception handler, your code looks more like this: 

TRY TO DO THE FOLLOWING: 
create a file object 
open the file 
allocate a buffer 
read the contents of the file 
close the file 

CATCH ANYTHING THAT WENT WRONG: 

if the file object was created, delete it 
if the buffer was allocated, release it 
if the file is still open, close it 

The normal portion is called the try handler, and the portion that handles 
abnormal conditions is called the catch handler. A routine in the try block 
can raise an exception to stop normal operation and go to a catch block. 
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The routine that raises an exception is called Failure. The exception han¬ 
dling mechanism has several utility routines that test their parameters and 
call Failure for you if an error actually occurred. These routines are de¬ 
scribed later on page 115 . 

The exception handling mechanism keeps a stack of catch handlers. If a rou¬ 
tine raises an exception, and there is no catch handler in the routine, control 
passes to the most recent catch handler. The THINK Class Library has a catch 
handler in CApplication’s Run method, so any exception is always caught. 

Suppose you have three functions, and each with a catch and try handler: 

function A 
TRY 

call B 
CATCH 

clean up A 

end 

function B 
TRY 

call C 
CATCH 

clean up B 

end 

function C 
TRY 

do something 
CATCH 

clean up C 

end 

If an operation in function C’s try handler raises an exception, control passes 
to C’s catch handler. When that handler is finished, control passes to B’s 
catch handler, and then finally to A’s catch handler. If B had no catch han¬ 
dler, control would go from C’s catch handler to A’s catch handler. 

Not every routine needs to have try and catch handlers, just those that would 
need to clean up if an error had occurred. Some of the time, you can rely on 
a caller’s catch handler to do the cleanup for you. 

Using the Exception Mechanism 

The exception handling mechanism is conceptually the same in both THINK 
C and in THINK Pascal, but, because of differences in the languages, you 
use them differently. In THINK C, the exception handler uses C macros to di- 
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See page 466 for a descrip¬ 
tion of the Err or Alert 
utility routine. 
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vide the normal portion of your functions from the exception portions. In 
THINK Pascal, it uses nested procedures. 

This section discusses some aspects of exception handlers common to both 
languages. The next two sections cover specific aspects of the exception 
handler for THINK C and for THINK Pascal. 

Exception handling conventions 

Regardless of the language you’re using, you should follow certain conven¬ 
tions for writing try and catch handlers. 

If an object cannot be created (that is, if a call to new fails) the THINK Class 
Library raises an exception with FailNIL. In THINK C, CObject’s 
operator new is overridden. In THINK Pascal, you must use 
TCLRuntime.lib. 

Once you’ve created an object successfully, you need to make sure that it 
will be released if the initialization fails. You can set up a catch handler to dis¬ 
pose of the object, or, if the object reference is an instance variable of anoth¬ 
er class, you can rely on its catch handler to dispose of the object. The 
examples below show you how to do this. 

Make sure that you set all object references to NIL before you create them 
with new. This way you can tell whether the object was created because the 
object reference will be non-NIL. 

The memory management methods are designed to protect your application 
from running out of memory in extreme circumstances. In normal operation, 
you should check all of your memory allocations without relying on the 
memory reserves. See page 138 for more inf ormation about handling low 
memory situations. 

Displaying error messages 

Since catch handlers propagate, you can rely on the top-level catch handler 
in CApplication’s Run method to display an error message. If you want to 
display your own message, you have to make sure that the catch handler in 
Run does not display a message. 

When a try handler wants to raise an exception, it calls Failure, which 
takes two arguments: the error that caused the failure and a message. These 
two values are saved in the globals gLastError and gLastMessage. 
The error is typically an operating system error. The message is optional. It’s 
used by the ErrorAlert routine to find an error string to display. 
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Note 

In Pascal, you can look at the parameters of the catch han¬ 
dler procedure to determine the error and message values. 

You can display your own error message in your catch handler. If you do, be 
sure to call SetFaillnf o with an error code kSilentError. This special 
error code tells the top-level handler not to display an error message at all. 
Whatever you pass to SetFaillnf o as the message is ignored. 

Exception Handling in THINK C 

In THINK C, you use the TRY, CATCH, and ENDTRY macros to write excep¬ 
tion handlers. The macros are defined in Exceptions . h. 

The basic form 

This is the basic form for writing an exception handler in C: 

void Example(void) 

{ 

TRY { 

This is the normal flow. 

Anything here can raise an exception that will be 
caught in the catch handler. 

} 

CATCH { 

This is the catch handler. 

Clean up after errors here: close files, release memory, etc. 

} 

ENDTRY; 

} 

Here’s a concrete example: 

void Example (void) 

{ 

CThing *anObject = NULL; 

TRY { 

anObject = new CThing; 
anObject->IThing() ; 

} 

CATCH { 

ForgetObject(anObject); 

} 

ENDTRY; 

} 

Example 8-1 A simple exception handler in C 
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In Example 8-1, there are two places where an exception can be raised. First, 
when you create anOb ject, there may not be enough memory. If that’s the 
case, new fails and raises an exception. Second, an operation in the I Thing 
initialization method may raise an exception. In either case, control passes 
to the catch handler. 

If new failed, anOb ject will be NULL, so the call ForgetOb ject won’t do 
anything, and there’s no other cleanup to do. If new succeeded, then the ex¬ 
ception was caused by some operation in I Thing. In that case, 

ForgetOb ject sends a Dispose message to anOb ject to release it. 

Use handlers only when necessary 

You don’t need a catch handler every time you create an object if you know 
that it will be disposed of by another handler. Here’s an example of that: 

void CMyApp::CreateDocument(void) 

{ 

CMyDoc *newDoc = NULL; 

TRY { 

newDoc = new CMyDoc; 
newDoc->IMyDoc(...); 
newDoc->NewFile(); 

} 

CATCH { 

ForgetObject(newDoc); 

} 

ENDTRY; 

} 

void CMyDoc::NewFile(void) 

{ 

BuildWindow(); 
itsWindow->Select() ; 

} 

void CMyDoc::BuildWindow() 

{ 

CCoolPane *myPane; 

itsWindow = new CWindow; 
itsWindow->IWindow(...); 

myPane = new CCoolPane; 
myPane->ICoolPane(...); 

} 

Example 8-2 A set of routines with only one catch handler in C 
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In Example 8-2 only CMyApp: :CreateDocument needs a catch handler. 
Here’s why. BuildWindow creates a window and immediately stores into 
itsWindow, which is an instance variable in CMyDoc. BuildWindow also 
creates a pane, which is immediately added into the view hierarchy by 
ICoolPane. If an exception is raised, it will be caught in CreateDocu- 
ment’s catch handler, which calls ForgetOb ject. ForgetOb ject sends 
a Dispose message to newDoc, which sends a Dispose message to 
itsWindow, which in turn disposes of all the panes that the window en¬ 
closes. 

Returning values 

If your function returns a value, you must not return from the try handler. In¬ 
stead, your function should return after END TRY. For example, look at 
CDataFile:iReadAll: 

Handle CDataFile:iReadAll (void) 

{ 

register OSErr errCode; 
long length; 

Handle contents = NULL; 

TRY 

{ 

FailOSErr(GetEOF(refNum, &length)); 
contents = NewHandleCanFail(length); 

FailNIL(contents); 

FailOSErr(SetFPos(refNum, 

fsFromStart, OL)); 

FailOSErr(FSRead(refNum, &length, 

♦contents)) ; 

} 

CATCH 

{ 

ForgetHandle(contents); 

} 

ENDTRY; 

return contents; 

} 

Example 8-3 Returning from a function with try and catch handlers 

The ReadAll method in Example 8-3 is a good example of using the excep¬ 
tion handling mechanism. Note how all of the File Manager routines that re¬ 
turn error codes are wrapped in calls to FailOSErr. This utility function 
checks the error return value, and if it is not noErr, it raises an exception. 
Note also how the function uses NewHandleCanFail to allocate a handle. 
That function ensures that the memory manager won’t use any of the memo- 
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ry reserves to get memory. The call toFailNIL raises an exception if the 
handle couldn’t be allocated. 

Special cases 

In some abnormal cases, you may want to keep catch handlers from propa¬ 
gating to the top-level handler in CApplication: : Run. If so, just use the 
macro NO_P ROP AG ATE somewhere in your catch handler. 

If you think you can fix whatever raised the exception in your catch handler, 
you can use the RETRY macro to retry the try handler: 

void Example(void) 

{ 

TRY { 

something that might raise an exception 

} 

CATCH { 

fix the problem 
RETRY; 

} 

ENDTRY; 

} 

Example 8-4 Using RETRY 

Exception Handling in THINK Pascal 

In THINK Pascal, you use a nested procedure to write an exception handler. 
Before the main flow of control, you use the CatchFailures procedure to 
set up the nested procedure as the exception handler. Your routine must 
also declare a variable of type Fail Inf o to hold the information the excep¬ 
tion handling mechanism needs. 


Warning 

For the exception handler to work correctly under the 
THINK Pascal environment, you must have debugging en¬ 
abled for all procedures and functions that may raise an ex¬ 
ception. The exception mechanism works correctly when 
you build an application. 


The basic form 

This is the basic form for writing an exception handler in Pascal: 

procedure Example; 
var 

fi: Faillnfo; { info for exception handler } 
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procedure HandleFailure (error: integer; 

message: longint); 

begin 

This is the catch handler. 

Clean up after errors here: 
close files, release memory, etc. 
end; 

begin 

CatchFailures(fi, HandleFailure); 

This is the normal flow. 

Anything here can raise 
an exception that will be 
caught in the catch handler. 

Success; 

end; 

Note that you must declare a variable of type Faillnf o in the main proce¬ 
dure. By convention, this variable is called fi. To set up the exception han¬ 
dler, you call the procedure CatchFailures and pass it the f i variable and 
the name of the nested procedure that serves as the catch handler. Finally, 
you must call Success to let the exception handler know that the main 
flow of code executed successfully. 

The catch handler is always a nested procedure declared like this: 

procedure HandleFailure (error: integer; 
message: longint); 

Error and message are the values that were passed to the Failure rou¬ 
tine to raise the exception. Typically, error is a Macintosh error code, and 
message is an optional application-specific description of what went 
wrong. 
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Here’s a concrete example: 

procedure Example; 
var 

anObject: CThing; 
f i : Faillnf De¬ 
procedure HandleFailure (error: integer; 

message: longint); 

begin 

ForgetObject(anObject); 
end; 

begin 

anObject := NIL; 

CatchFailures (fi, HandleFailure); 

new(anObject); 
anObject.IThing; 

Success' 

end; 

Example 8-5 A simple exception handler in Pascal 

In Example 8-1, there are two places where an exception can be raised. First, 
when you create anObject, there may not be enough memory. If that’s the 
case, new fails and returns NIL. Second, an operation in the IThing initial¬ 
ization method may raise an exception. In either case, control passes to the 
catch handler. 

If new failed, anObject will be NIL, so the call ForgetObject won’t do 
anything, and there’s no other cleanup to do. If new succeeded, then the ex¬ 
ception was caused by some operation in IThing. In that case, 
ForgetObject sends a Dispose message to anObject to release it. 

Use handlers only when necessary 

You don’t need a catch handler every time you create an object if you can be 
sure that it will be disposed of properly by another handler. Here’s an exam¬ 
ple of that: 

procedure CMyApp.CreateDocument; 
begin 
var 

newDoc: CMyDoc; 
fi: Faillnfo; 

procedure HandleFailure (error: integer; 
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message: longint); 

begin 

ForgetObject(newDoc); 
end; 

begin 

newDoc := NIL; 

CatchFailures(fi, HandleFailure); 

new(newDoc); 
newDoc.IMyDoc(...); 
newDoc.NewFile; 

Success; 

end; 

procedure CMyDoc.NewFile; 
begin 

BuildWindow; 
itsWindow.Select; 
end; 

procedure CMyDoc.BuildWindow; 
var 

myPane: CCoolPane; 
tmpWin: CWindow; 

begin 

new (tmpWin) ; 
itsWindow := tmpWindow; 
itsWindow.IWindow(...); 

new(myPane); 

myPane.ICoolPane(...); 

end; 

Example 8-6 A set of routines with only one catch handler in Pascal 

In Example 8-2 only CMyApp. CreateDocument needs a catch handler. 
Here’s why. BuildWindow creates a window and immediately stores into 
itsWindow, which is an instance variable in CMyDoc. BuildWindow also 
creates a pane, which is immediately added into the view hierarchy by 
ICoolPane. If an exception is raised, it will be caught in CreateDocu- 
ment’s catch handler, which calls ForgetObject. ForgetObject sends 
a Dispose message to newDoc, which sends a Dispose message to 
it sWindow, which in turn disposes of all the panes that the window en¬ 
closes. 


7 1 2 Object-Oriented Programming 


Exception Handler Routines 


♦ 


Using Exit with exception handlers 

If you use the Pascal keyword Exit to leave a function or procedure that 
has a catch handler, be sure that you call Success first. Otherwise, the ex¬ 
ception mechanism will get confused. 

Special cases 

In some abnormal cases, you may want to keep catch handlers from propa¬ 
gating to the top-level handler in CApplication. Run. If so, you should 
insert a label after the call to Success in the try handler and goto it from 
your catch handler. 

If you think you can fix whatever raised the exception in your catch handler, 
you can use the RetryException procedure to retry the try handler: 

procedure Example; 
var 

fi: Faillnfo; 

procedure HandleFailure (error: integer; 

message: longint); 

begin 

fix the problem 
RetryException(fi); 
end; 

begin 

something that might raise an exception 
end; 

Example 8-7 Retrying the try handler 

Exception Handler Routines 

These routines form the exception handling mechanism. Your program 
should use the error detection routines to test the return values of Macintosh 
Toolbox routines. 

Exception handler routines 

If you’re a Pascal programmer, you should only use CatchFailures, 
Success, and RetryException. If you’re a C programmer, the TRY, 
CATCH, and ENTRY macros call these routines for you. 
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CatchFallures 


PushTryHandler 


Success 


RetryException 


Failure 


procedure CatchFailures (var fi: Faillnfo; 
procedure handler (error: integer; 

message: longint)); 

Pascal only 

This procedure sets up a catch handler. Fi is a variable of type Faillnfo 
declared in the outer procedure or function. Handler is the name of a nest¬ 
ed procedure that will serve as the catch handler.The catch handler is always 
a nested procedure declared like this: 

procedure HandleFailure (error: integer; 
message: longint); 

Error and message are the values that were passed to the Failure rou¬ 
tine to raise the exception. Typically, error is a Macintosh error code, and 
message is an optional application-specific description of what went 
wrong. 

C only 

void PushTryHandler (Faillnfo *fi); 

Push an exception handler on the exception stack. This function is called by 
the TRY macro. You should not need to call this function yourself. 

procedure Success; 
void Success (void); 

Pop the most recent exception handler off the exception stack. In THINK 
Pascal, you should call this procedure after all the code that could have 
failed has executed successfully. In THINK C, the CATCH macro calls this 
function for you. 

procedure RetryException (var fi: Faillnfo); 
void RetryException (Faillnfo *fi); 

Retry the try handler. In THINK Pascal you can call this procedure if you can 
fix the problem in the catch handler. In THINK C, you should use the RETRY 
macro in the catch handler. 

Exception raising routine 

procedure Failure (error: integer; message: longint); 
void Failure (short error, long message); 

Raise an exception. Set gLastError to error and gLastMessage to mes¬ 
sage. If error is not kSilentError, the catch handler in CApplication’s 
Run method displays an error alert. 
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FailMemError 


FailNIL 


FailResError 


FailNILRes 


FailOSErr 


SpedfyMsg 


For an explanation of the message parameter, see the description of 
ErrorAlert on page 466 

Error detection routines 

These routines test their arguments or check Toolbox error-reporting func¬ 
tions to raise and exception if an error has occurred. You should use these 
routines any time you call any Toolbox routines that returns an error code, 
that deals with resources, or moves memory. 

procedure FailMemError; 
void FailMemError (void); 

Raise an exception if the Toolbox function MemError returns anything but 
noErr. Calls Failure (memoryError, 0). 

procedure FailNIL (p: UNIV Ptr); 
void FailNIL (void *p); 

Raise an exception if p is NIL. Calls Failure (memFullError, 0 ). 

procedure FailResError; 
void FailResError (void); 

Raise an exception if the Toolbox function ResError returns anything but 
noErr. Calls Failure (resourceError, 0). 

procedure FailNILRes (resH: UNIV Handle); 
void FailMemError (void resH); 

Raise an exception is resH, a resource handle, is NIL. If ResError returns 
noErr, call Failure (resNotFound, 0). Otherwise, calls 
Failure(resourceError, 0). 

procedure FailOSErr (errCode: OSErr); 
void FailOSErr (OSErr errCode); 

Raise an exception if errCode is anything but noErr. This function calls 
Failure(errCode, 0). 

Utility routines 

function SpecifyMsg (strListID:integer; 
strlndex: integer): longint; 

long SpecifyMsg (short strListID, short strlndex); 
Create a message value. StrListID is the resource ID of a STR# resource, 
and strlndex is the index into that resource. The value returned should be 
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SetFalllnfo 


passed to Failure (or one of the routines that calls Failure). See the de¬ 
scription of Err or Alert on page 466 for more information. 

procedure SetFaillnfo (newError: integer; 
newMessage: longint); 

void SetFaillnfo (short newError, long newMessage); 

Set the global variables gLastError and gLastMessage. If gLastMessage is not 
zero, this routine doesn’t reset it. GLastError is always set. 

Although it’s usually used internally by the exception handling mechanism, 
you should call SetFaillnfo (kSilentError, 0) to prevent the top- 
level exception handler from displaying an error message. 
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Introduction 

CAbstractText is an abstract class that provides you with a template for creat¬ 
ing a pane that displays text. 

Heritage 

Superclass CPanorama 

Subclasses CEditText 

Using CAbstractText 

CAbstractText is an abstract class for creating panes that display text. A text 
pane is usually the panorama in a scroll pane so you can scroll through the 
text. The Specify method, on page 120, lets you choose whether the user 
can edit and copy your text pane’s text. The DoCommand method, on page 
122, handles all the common text editing commands such as cutting and 
pasting, font selection, line spacing, etc. 

To handle the Undo command, CAbstractText creates task objects for many 
common commands and sends messages to the object telling it to perform 
or undo its task. CTextEditTask on page 421 handles typing, cutting, copy¬ 
ing, and pasting. CTextStyleTask on page 427 handles font, size, and style 
commands. 

When you perform a task that can be undone, the name of the Undo comm- 
aond changes, for example Undo Typing. The Undo labels for this CAb¬ 
stractText are stored in the resource STR# 130. The index of the first string is 
stored in the class variable cFirstTasklndex. By default, it’s 1. If you put 
the strings in a different place in STR# 130, you should set this variable to the 
index of the first string. If you don’t use Undo labels, set this variable to 0. 
The labels must be in this order: Typing, Cut, Copy, Paste, Clear, Formatting. 
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Since it’s an abstract class, you can’t create an instance of CAbstractText. You 
can use the CEditText or CStyleText classes that come with the THINK Class 
Library. 

These classes are based on the Macintosh TextEdit (TE) routines and be¬ 
come slow if they contain over 4000 characters. If your text pane needs to 
handle more text, create your own subclass of CAbstractText. 

Most of CAbstractText’s methods do nothing. They are “place holders” for 
the methods your subclass must override. The rest of CAbstractText’s meth¬ 
ods call them. These are the methods you must override: 


DoClick 

GetTextHandle 

SetFontStyle 

SetTextMode 

SetAlignCmd 

GetHeight 

GetCharPoint 

GetCharStyle 

GetLength 

SetSelection 

GetSelection 

CopyTextRange 

InsertTextPtr 


SetTextPtr 

SetFontNumber 

SetFontSize 

SetAlignCmd 

SetSpacingCmd 

GetCharOffset 

GetTextStyle 

FindLine 

TypeChar 

GetSpacingCmd 

GetNumLines 

PerformEditCommand 

Dawdle 


These two methods assume that the text in your pane is stored in a single 
contiguous buffer. If it’s not, you should override them: 

GetCharBefore GetCharAfter 

Variables 

This is an instance variable that any class can use. 

Variable Type Description 

i t s TypingT a s k CTex t Edi t T a s k Active typing task. 

CFirstTasklndex is a class variable that only CAbstractText and its sub¬ 
classes should use. In THINK C, it’s a class variable. 


Variable 

Type 

Description 

CFirstTasklndex 

short 

Index in STR# 130 



resource of first 



undo label 
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These are internal instance variables which only subclasses of CAbstractText 
should use. In THINK C, they are protected. 


Variable 

Type 

Description 

lineWidth 

integer 

Width of a text line 
in pixels. If nega¬ 
tive, lines are as 
wide as the pane. 

fixedLineHeights 

Boolean 

TRUE if all lines 
same height. 

wholeLines 

Boolean 

TRUE if lines aren’t 
cut off vertically. 

lastFontNum 

integer 

Last font number. 

lastFontCmd 

longint 

Last font command 
number. 

lastTextSize 

integer 

Last seen text size 

lastSizeCmd 

longint 

Last size command 
number. 

editable 

Boolean 

TRUE if user can edit 

text 

stylable 

Boolean 

TRUE if user can 
change font, size, or 
style of text. 


Methods 

Construction and destruction methods 

procedure lAbstractText (anEnclosure: CView; 
aSupervisor: CBureaucrat; 
aWidth, aHeight: integer; 
aHEncl, aVEncl: integer; 
aHSizing, aVSizing: SizingOption; 
aLineWidth: integer); 

void lAbstractText (CView *anEnclosure, 

CBureaucrat *aSupervisor, 
short aWidth, short aHeight, 
short aHEncl, short aVEncl, 

SizingOption aHSizing, SizingOption aVSizing, 
short aLineWidth); 

Initialize an abstract text pane. Most of the arguments to this method are 
identical to pane initialization. ALineWidth specifies how wide the lines 
should be. If it’s less than zero, the text wraps to the width of the pane. 
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Note 

The descriptions of the other arguments are in CPane. 


IViewRes procedure IViewRes (rType:ResType; resID: integer; 

anEnclosure: CView; aSupervisor: CBureaucrat); 

void IViewRes (ResType rType, short resID, 

CView *anEnclosure, CBureaucrat *aSupervisor); 

Initialize edit text pane from a resource template. RType is the resource type 
for the CView subclass you want to initialize. ResID is the resource ID of 
the resource. AnEnclosure and aSupervisor are the enclosure and su¬ 
pervisor of the pane. 

To initialize a text pane from a resource file, use a 1 AbTx 1 resource. 


Note 

Earlier versions of the THINK Class Library used 1 StTx 1 
resources to initialize static text and edit text panes. You 
should make sure that any old programs do not use 
1 StTx 1 . 


Free/Dispose procedure Free; 

void Dispose (void); 

Dispose of an abstract text object. 

Accessing method 

Specify procedure Specify (fEditable, fSelectable, fStylable: 

Boolean); 

void Specify (Boolean fEditable, 

Boolean fSelectable, Boolean fStylable); 

Specify whether the user can edit, select, and style text. This method sets 
editable to fEditable, wantsClicks to fSelectable, and 
stylable to fStylable. By default, text is editable, selectable, and sty- 
lable. If editing is allowed, you can insert and delete text. If selecting is al¬ 
lowed, you can select text to copy it to the clipboard. If styling is allowed, 
the user can change have change the font, style, or size of the text. 

To make your Speci f y calls more understandable, the THINK Class Library 
defines some constants you can use instead of TRUE and FALSE: 
kEditable kNotEditable 

kSelectable kNotSelectable 

kStylable kNotStylable. 
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This list describes some common ways to call Specify: 

• To let the user edit and style text, call 

Specify(kEditable, kSelectable, kStylable). 

• To prevent the user from editing, styling, or selecting text, call 
Specify(kNotEditable, kNotSelectable, 
kNotStylable). 

• To let the user select text (to copy it, for example) but not edit or 
style it, call Specify (kNotEditable, kSelectable, 
kNotStylable) 

• To let the user edit text, but not style it, call 

Specify(kEditable, kSelectable, kNotStylable). 

• To let the user style text, but not edit it, call 

Specify(kNotEditable, kSelectable, kStylable) 


Note 

If f Selectable is kNotSelectable, Specify dis¬ 
ables editing and styling , regardless of the values of 
fEditable and fStylable. 


You can call Specify at any time. For example you could lock text (that is, 
disable editing) to prevent accidental editing, then let the user unlock it later 
to edit it. 

procedure GetSpecification (var fEditable, 
fSelectable, fStylable: Boolean); 

void GetSpecification (Boolean *fEditable, 

Boolean *fSelectable, Boolean *fStylable); 

Return whether this pane is editable, stylable, and selectable. 
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DoCommand 


UpdateMenus 


Command methods 

procedure DoCommand (theCommand: longint); 
void DoCommand (long theCommand); 

This method handles the common commands that apply to text: cutting and 
pasting, font selection, styling, alignment, and spacing. DoCommand handles 
these commands: Qt passes all other commands to its supervisor.) 

• Editing commands: cmdCut, cmdCopy, cmdPaste, cmdClear, 
cmdSelectAll 

• Style commands: cmdPlain, cmdBold, cmdltalic, 
cmdUnderline, cmdOutline, cmdShadow, cmdCondense, 
cmdExtend 

• Alignment commands: cmdAlignLef t, cmdAlignCenter, 
cmdAlignRight 

• Spacing commands: cmdSingleSpace, cmdlHalf Space, 
cmdDoubleSpace. 

• Font selection from the Font menu (MENUf ont) 

• Size selection from the Size menu (MENUsi ze) 

To let the user undo actions, this method creates a task object for most com¬ 
mands. It creates a CTextEditTask object for an editing command and a 
CTextStyleTask object for a style, alignment, spacing, font, or size command. 

procedure UpdateMenus; 
void UpdateMenus (void); 

Update the menus that have to do with text processing right before the 
menu appears. This method enables the Cut, Copy, and Clear commands if 
there is a current selection and enables the Paste command if there is text in 
the clipboard. This menu also checks the current font, size, style, alignment, 
and spacing commands. 


Note 

See the implementation of this method if you want an ex¬ 
ample of how to write your own UpdateMenus method. 
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DoAutoKey 


Perform EditCom mand 


TypeChar 
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procedure DoKeyDown (theChar: char; keyCode: Byte; 
macEvent: EventRecord); 

void DoKeyDown (char theChar, Byte keyCode, 

EventRecord *macEvent); 

Handle a key down in a text pane. Usually, this passes function and com¬ 
mand keys to its superclass and inserts other characters into the text. This ta¬ 
ble shows how it handles command keys and function keys: 

If the key Is... This method... 

Any command key Passes it to the superclass. 

Home, Page Up, Page Down Passes it to the superclass. 

End Scrolls to the bottom left of the 

text. 

A cursor key Calls TypeChar and notifies the 

editing task of the change in the 
selection. 

Any other key Passes it to the editing task, which 

should insert the character if the 
text pane is editable. 

procedure DoAutoKey (theChar: char; keyCode: Byte; 
macEvent: EventRecord); 

void DoAutoKey (char theChar, Byte keyCode, 

EventRecord *macEvent); 

Handle an auto-key in a text pane. If the command key is down, this method 
does nothing. Otherwise, this method calls DoKeyDown. 

procedure PerformEditCommand (theCommand: longint); 
void PerformEditCommand (long theCommand); 

Perform the standard cut, copy, paste, and clear commands on the text. The 
task classes call this method to perform and undo an edit command. The de¬ 
fault method does nothing. Your subclass must override this method. 

procedure TypeChar (theChar: char; 
theModifiers: integer); 

void TypeChar (char theChar, short theModifiers); 

Process a keystroke. This method does not need to set up for an Undo com¬ 
mand and should handle the key directly. The task classes call this method 
to perform a key stroke. The default method does nothing. Your subclass 
must override this method. 
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SelectionChanged 


MakeEditTask 


MakeStyleTask 


BecomeCopher 


ScrollToSelection 


SetSelection 


procedure SelectionChanged; 
void SelectionChanged (void); 

The selection has just changed This method sends a BroadcastChange 
message with textSelectionChanged as the reason. If this text pane 
has an editing task, it sends the task a SelectionChanged message. 

function MakeEditTask (editCmd: longint): 
CTextEditTask; 

CTextEditTask *MakeEditTask (long editCmd); 

Create a task to handle typing and the cut, copy, paste, and clear commands. 
This method creates a CTextEditTask class. If you override this method, it 
must create a subclass of CTextEditTask. In THINK C MakeEditTask is a 
protected method. 

function MakeStyleTask (styleCmd: longint): 
CTextStyleTask; 

CTextStyleTask *MakeStyleTask (long editCmd); 

Create a task to handle font, style, size, alignment, and spacing commands. 
This method creates a CTextStyleTask class. If you override this method, it 
must create a subclass of CTextStyleTask. In THINK C MakeStyleTask is a 
protected method. 

procedure BecomeGopher (fBecoming: Boolean); 
void BecomeGopher (Boolean fBecoming); 

If fBecoming is TRUE, this text pane is becoming the gopher. This method 
activates it and enables the Font, Size, and Style menus. Otherwise, this text 
pane is no longer the gopher. This method deactivates the pane and disables 
the Font, Size, and Style menus. 

Display methods 

procedure ScrollToSelection; 
void ScrollToSelection (void); 

Scroll so the current selection is visible. 

procedure SetSelection (selStart, selEnd: long; 
fRedraw: Boolean); 

void SetSelection (long selStart, long selEnd, 

Boolean fRedraw); 

Set the selection to the range corresponding to character positions 
selStart through selEnd. The default method does nothing. Your sub¬ 
class must override this method. 
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CetSelection 


SelectAII 


Paginate 


SetTextString 


SetTextHandle 


SetTextPtr 


GetTextHandle 


procedure GetSelection (var selStart, selEnd: 
longint); 

void GetSelection (long *selStart, long *selEnd); 

Return the start and end of the current selection. The default method does 
nothing. Your subclass must override this method. 

procedure SelectAII (fRedraw: Boolean); 
void SelectAII (Boolean fRedraw); 

Select all the text in this text pane. This method uses Get Length to deter¬ 
mine the length of the text. 

procedure Paginate (aPrinter CPrinter; 
pageWidth, pageHeight: integer); 

void Paginate (struct CPrinter *aPrinter, 
short pageWidth, short pageHeight); 

Split the text pane into pages. This method makes sure that lines aren’t cut in 
half horizontally at the ends of pages. 

Text specification methods 

procedure SetTextString (textStr: Str255); 
void SetTextString (Str255 textStr); 

Use the specified string as the text pane’s text This method uses SetTex¬ 
tPtr to set the text. 

procedure SetTextHandle (textHand: Handle); 
void SetTextHandle (Handle textHand); 

Use the text textHand as the text for this text pane. This method uses Set¬ 
TextPtr to set the text. 

procedure SetTextPtr (textPtr: Ptr; 
numChars: longint); 

void SetTextPtr (Ptr textPtr, long numChars); 

Use the first numChars characters that textPtr points to as the text for 
this abstract text object The default method does nothing. Your subclass 
must override this method so it makes a copy of the text. 

function GetTextHandle: CharsHandle; 

CharsHandle GetTextHandle (void); 

Return a handle to the text of the abstract text. The default method does 
nothing. Your subclass must override this method. In most cases, the text 
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CopyTextRange 


InsertTextPtr 


InsertTextHandle 


GetCharBefore 


GetCharAfter 


class should keep its text in a handle, and this method should return that 
handle—not a copy of it 

If your implementation requires that this method return a copy of the text in 
a handle, your subclass should override any methods that call 
Get Text Handle to dispose of the handle. In CAbstractText, the methods 
GetCharBefore and GetCharAfter expect GetTextHandle to return 
a handle to the actual text. 

function CopyTextRange (start, end: long): Handle; 
Handle CopyTextRange (long start, long end) ; 

Return a copy of the text specified by start and end. The default method 
does nothing. Your subclass must override this method. 

procedure InsertTextPtr (text: Ptr; length: longint; 
fRedraw: Boolean); 

void InsertTextPtr (Ptr text, long length. 

Boolean fRedraw); 

Insert a copy of the given text at the start of the selection. Text is a pointer 
to the text. The default method does nothing. Your subclass must override 
this method. 

procedure InsertTextHandle (text: Handle; 
fRedraw: Boolean); 

void InsertTextHandle (Handle text. Boolean fRedraw); 
Insert a copy of the given text at the start of the selection. Text is a handle 
to the text. 

procedure GetCharBefore (var aPosition: longint; 
var charBuf: tCharBuf); 

void GetCharBefore (long *aPosition, 
tCharBuf charBuf); 

Return the character before aPosition. The character and its size are re¬ 
turned in charBuf, and aPosition is updated with the starting position 
of the character. If there is no character after aPosition, then this method 
sets the length of the character to 0 (zero) and does not update aPosition. 

procedure GetCharAfter (var aPosition: longint; 
var charBuf: tCharBuf); 

void GetCharAfter (long *aPosition, 
tCharBuf charBuf); 

Return the character after aPosition. The character and its size are re¬ 
turned in charBuf, and aPosition is updated with the starting position 


126 Object-Oriented Programming 



Methods 


SetFontNumber 


SetFontName 


SetFontStyle 


SetFontSize 


SetTextMode 


SetAlignCmd 


- ♦ 

of the character. If there is no character before aPosition, then this meth¬ 
od sets the length of the character to 0 (zero) and does not update 
aPosition. 

Text characteristics methods 

procedure SetFontNumber (aFontNumber: integer); 
void SetFontNumber (short aFontNumber); 

Set the font by font number. The default method does nothing. Your sub¬ 
class must override this method. If your subclass supports multiple fonts in a 
pane, this method should set the font for the current selection. Otherwise, it 
should set the font for the whole text pane. 

procedure SetFontName (aFontName: Str255); 
void SetFontName (Str255 aFontName); 

Set the font by font name. 

procedure SetFontStyle (aStyle: Style); 
void SetFontStyle (short aStyle); 

Set the font style. AStyle may be one of: bold, italic, underline, 
outline, shadow, condense, or extend The default method does 
nothing. Your subclass must override this method. If your subclass supports 
multiple styles in a pane, this method should set the style for the current se¬ 
lection. Otherwise, it should set the style for the whole text pane. 

procedure SetFontSize (aSize: integer); 
void SetFontSize (short aSize); 

Set the font size to the specified size. The default method does nothing. Your 
subclass must override this method. If your subclass supports multiple styles 
in a pane, this method should set the size for the current selection. Other¬ 
wise, it should set the size for the whole text pane. 

procedure SetTextMode (aMode: integer); 
void SetTextMode (short aMode); 

Set the text mode to the specified mode. AMode can be one of srcOr, 
srcXor, or srcBic. The default method does nothing. Your subclass must 
override this method. 

procedure SetAlignCmd (anAlignment: long); 
void SetAlignCmd (long anAlignment); 

Set the text alignment. AnAlignment can be one of cmdAlignLef t, 
cmdAlignRight, or cmdAlignCenter. The default method does noth- 
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GetAlignCmd 


SetSpadngCmd 


GetSpadngCmd 


GetHeight 


Getl Height 


GetCharOffset 


ing. Your subclass must override this method. If your subclass supports mul¬ 
tiple alignments in a pane, this method should set the alignment for the 
current selection. Otherwise, it should set the alignment for the whole text 
pane. 

function GetAlignCmd: longint; 
long GetAlignCmd (void); 

Return the current alignment. It can be one of cmdAlignLef t, 
cmdAlignRight, cmdAlignCenter, orcmdNull. The default method 
does nothing. Your subclass must override this method. If your subclass al¬ 
lows different alignments within a text pane and the current selection con¬ 
tains more than one alignment, this method should return cmdNull. 

procedure SetSpacingCmd (aSpacingCmd: longint); 
void SetSpacingCmd (long aSpacingCmd); 

Set the space between lines of text. ASpacingCmd can be one of 
cmdSingleSpace, cmdlHalf Space, or cmdDoubleSpace. The default 
method does nothing. Your subclass must override this method. 

function GetSpacingCmd: longint; 
long GetSpacingCmd (void); 

Return the space between lines of text. It can be one of cmdSingleSpace, 
cmdlHalf Space, or cmdDoubleSpace. The default method does noth¬ 
ing. Your subclass must override this method. 

function GetHeight (startLine endLine: longint): 
longint; 

long GetHeight (long startLine, long endLine); 

Return the total height in pixels of the indicated lines of text The default 
method does nothing. Your subclass must override this method. 

function GetlHeight (aLineNum: longint): integer; 
short GetlHeight (long aLineNum); 

Return the height in pixels of the indicated line of text 

function GetCharOffset (aPt: LongPt): longint; 
long GetCharOffset (LongPt *aPt); 

Return the character position nearest the coordinate aPt. APt must be in 
frame coordinates. The default method does nothing. Your subclass must 
override this method. 
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GetCharPoint 


GetCharStyle 


GetTextStyle 


SetWholeLines 


GetWholeLines 


procedure GetCharPoint (offset: long; 
var aPt: LongPt); 

void GetCharPoint( long offset, LongPt *aPt); 

Return the coordinates of the character position offset. APt is in frame 
coordinates. The default method does nothing. Your subclass must override 
this method. 

procedure GetCharStyle (charOffset: long; 
var theStyle: TextStyle); 

void GetCharStyle (long charOffset, 

TextStyle *theStyle); 

Return style information for the character at position charOffset. 

procedure GetTextStyle (var whichAttributes: integer; 
var aStyle: TextStyle); 

void GetTextStyle (short *whichAttributes, 

TextStyle *aStyle); 

Return current style information. WhichAttributes is a flag that indicates 
which text attributes to report on. The default method does nothing. Your 
subclass must override this method. If your subclass supports multiple styles 
in a text pane, this method should report only on the attributes that are con¬ 
tinuous over the current selection, and set whichAttributes to those at¬ 
tributes. 

The attributes flags and Text Style record are described in Inside Macin¬ 
tosh VI, Chapter 15, “TextEdit.” 

Calibrating methods 

procedure SetWholeLines (aWholeLines: Boolean); 
void SetWholeLines (Boolean aWholeLines); 

If aWholeLines is TRUE, this method will resize the frame so it will display 
only whole lines. The text pane is not redrawn. 

function GetWholeLines: Boolean; 

Boolean GetWholeLines (void); 

Return the value of the wholeLines instance variable. If TRUE, the frame is 
set so it displays only whole lines and not partial lines. 
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ResizeFrame 


FindLine 


GetLength 


GetNumLines 


AdjustCursor 


procedure ResizeFrame (delta: Rect); 
void ResizeFrame (Rect *delta); 

Resize the frame when the size of its pane changes. The delta rectangle 
specifies how each side changes. Positive values mean down and to the 
right. Negative values mean up and to the left. 

function FindLine (charPos: integer) : longint; 
long FindLine (short charPos); 

Return the line number containing the specified character position. The de¬ 
fault method does nothing. Your subclass must override this method. 

Both line and character numbering start at zero. If the character position is 
before the start of the text (a negative number), this method should return 
zero. If the character position is beyond the end of the text, this method 
should return the number of the last line. 

function GetLength: longint; 
long GetLength (void); 

Return the length in bytes of the text buffer. The default method does noth¬ 
ing. Your subclass must override this method. 

function GetNumLines: longint 
long GetNumLines (void); 

Return the total number of lines in the text buffer. The default method does 
nothing. Your subclass must override this method. 

Cursor method 

procedure AdjustCursor (where: Point; 
mouseRgn: RgnHandle); 

void AdjustCursor (Point where, RgnHandle mouseRgn); 
Turn the cursor into an I-beam when the mouse is in the edit text pane. 
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Introduction 

CAppleEvent is a class that contains an AppleEvent and its default reply. The 
THINK Class Library handles the four required AppleEvents (Open Applica¬ 
tion, Open Documents, Print Documents, and Quit Application) and lets you 
use others. 

Heritage 

Superclass CObject 

Subclasses None 

Using CAppleEvent 

When your application receives an AppleEvent, the THINK Class Library 
puts in a CAppleEvent object and passes it to the gopher. You don’t need to 
write any code to handle the four required AppleEvents. The application 
handles them by default. 

If your application uses an AppleEvent besides the four required ones, you 
need to write a DoAppleEvent method to handle it. That method should 
be in the class that handles the event: your subclass of CPane, CDocument 
or CApplication. You don’t need to subclass CAppleEvent to handle new Ap¬ 
pleEvents. 

To extract the parameters from your AppleEvent, you can send it either a 
GetDescList message, on page 134, which returns items in a 
AEDescList, or an ExtractFromDescList message, on page 134, 
which returns its items in a CArray object. After you extract all the parame¬ 
ters you know about, send your AppleEvent a GotRequiredParam mes¬ 
sage, on page 134, which returns TRUE if you extracted all the required 
parameters. 

If your AppleEvent needs to interact with the user (e.g., display a dialog), 
send it the Request Interaction message, on page 134. The THINK 
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Class Library assumes that the AppleEvents Open Application and Open 
Documents do not require user interaction. If they do, you must override 
(^Application's DoAppleEvent method 

When your AppleEvent needs to return a result, send it a 
SetErrorResult message, described on page 135. If you need to store an 
error string or return data, send your AppleEvent object a GetAEReply 
message, described on page 134, and store that information directly in the 
reply. 

How the THINK Class Library handles AppleEvents 

When your initialize your application, it checks to see if the AppleEvent 
manager is installed. If it is, the switchboard installs a handler in the Ap¬ 
pleEvents dispatch table, called AppleEventHandler, that handles all Ap¬ 
pleEvents. 

When your application is running and the switchboard receives a high-level 
event, it assumes the event is an AppleEvent and calls 
AEProcessAppleEvent. That function, in turn, calls the handler 
AppleEventHandler, which the switchboard installed earlier. The han¬ 
dler sends the switchboard a DoAppleEvent message. That method pack¬ 
ages the AppleEvent and sends it to the gopher, which finds who will handle 
it. 

Variables 

These are internal instance variables which only subclasses of CAppleEvent 
should use. In THINK C, they are protected. 


Variable 

Type 

Description 

theEvent 

AppleEvent 

The AppleEvent. 

theReply 

AppleEvent 

The default reply. 

theRefCon 

longint 

The reference value. 

eventClass 

DescType 

The event class; e.g., 
1 aevt 1 . 

eventID 

DescType 

The event ID; e.g., 

*oapp *. 

canlnteract 

Boolean 

TRUE if interaction 
with the user has 
previously been re¬ 
quested and ap¬ 
proved. 

errCode 

OSErr 

The error code for 
this event. 
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GetEventClass 


GetEventID 


GetAEEvent 


Variable Type Description 

notif icationRec NMRec The Notification 

Manager record for 
AEInteractWith 
User. By default, 
it’s NULL 

idleProc IdleProcPtr The idle procedure 

for AEInteract- 
WithUser. If NULL, 
uses CSwitchboard’s 
idle procedure 

Methods 

Creation and destruction 

procedure lAppleEvent (theEvent, theReply: AppleEvent, 
theRefCon: longint, eventClass, eventID: DescType); 

void lAppleEvent (const AppleEvent *theEvent, 
const AppleEvent *theReply, long theRefCon, 

DescType eventClass, DescType eventID); 

Initialize a CAppleEvent object. TheEvent is the AppleEvent that CSwitch- 
Board received. TheReply is the default reply that the AppleEvent manager 
generates for an AppleEvent. TheRefCon is the reference value for this 
event’s class and ID. EventClass and eventID are the event class and ID 
from theEvent. 

Accessing methods 

function GetEventClass: DescType; 

DescType GetEventClass (void); 

Return the event class, e.g. ' aevt'. The event class and event ID uniquely 
identify an AppleEvent. 

function GetEventID: DescType; 

DescType GetEventID (void); 

Return the event ID, e.g. ' oapp'. The event class and event ID uniquely 
identify an AppleEvent 

function GetAEEvent: AppleEvent; 

AppleEvent GetAEEvent (void); 

Return the AppleEvent. 
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function GetAEReply: AppleEvent; 
AppleEvent GetAEReply (void); 
Return the AppleEvent reply. 


GetAERefCon function GetAERefCon: longint; 

long GetAERefCon (void); 

Return the AppleEvent reference value for this event’s class and ID. By de¬ 
fault, this is always zero in the THINK Class Library. To use other values, 
override the I Switchboard method in CSwitchboard, and change its call 
to AEInstallEventHandler. 


GetDescLlst procedure GetDescList (whichParam: AEKeyword; 

var descList: AEDescList); 

void GetDescList (AEKeyword whichParam, 

AEDescList *descList); 

Return the AEDescList associated with the keyword whichParam. 


ExtractFromDescLlst function ExtractFromDescList (whichParam: AEKeyword; 

itemType: DescType; itemSize: Size): CArray; 

CArray *ExtractFromDescList (AEKeyword whichParam, 
DescType itemType, Size itemSize); 

Get the descriptor list associated with the parameter whichParam, and puts 
its items into a CArray. This method is especially useful if all the items in the 
list are the same size and the data in the list is not keyword separated. This 
method does not use the keywords. 


GotRequiredParams function GotRequiredParams: Boolean; 

Boolean GotRequiredParams (void); 

Does the recommended check to determine if all the required parameters of 
an AppleEvent have already been extracted. You should call this method af¬ 
ter you extract all the parameters you know about and before you actually 
handle the event. 


Requestlnteractlon function Requestlnteraction (timeOutTicks: longint): 

OSErr; 

OSErr Requestlnteraction (long timeOutTicks) ; 

Indicates that you need to interact with the user (e.g. put up a dialog) to han¬ 
dle the event. If interaction is allowed and the application is brought forward 
before the timeout period has elapsed, then this method returns noErr and 
you can proceed with the interaction. If any other value is returned, then 
your attempt to interact failed. 
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This method calls AEInteractWithUser, with timeOutTicks, an idle 
procedure, and a pointer to a Notification Manager record. By default, the 
idle procedure sends the switchboard an Apple Event I die message, de¬ 
scribed on page 408. To use a different idle procedure, assign it to the 
idleproc instance variable. Also, the Notification Manager record pointer 
is NIL by default, so AEInteractWithUser supplies its own default 
record. To use your own record, assign it to the notif icationRec in¬ 
stance variable. 

procedure SetErrorResult (anErrorCode: OSErr); 
void SetErrorResult (OSErr anErrorCode); 

Set the result code for this event. If you successfully handle this function, set 
the result code to noErr. If you try to handle this function and fail, set the 
result code to appropriate error code. 

function GetErrorResult: OSErr; 

OSErr GetErrorResult (void); 

Return the error code for this event. If the event was handled successfully, it 
will be noErr . If the event was not handled, it will be 
errAEEventNotHandled. If someone attempted to handle it, failed, and 
stored a result code, it will be some other result code. CSwitchboard uses a 
special exception handler to trap exceptions raised during the handling of 
an AppleEvent, and will return the exception error instead. 
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Introduction 

Every program must create a subclass of CApplication and create only one 
instance of this class. The application is the highest level in the chain of com¬ 
mand. It is the only bureaucrat without a supervisor. 

Heritage 

Superclass CDirectorOwner 

Subclasses You must define a subclass of this class. 

Using CApplication 

CApplication is one of the classes you must override to implement an appli¬ 
cation with the THINK Class Library. An application usually has one or more 
subordinate directors which handle the interaction between commands 
and windows. The most common kind of director is a document which, in 
addition to a window, also handles a file. 

The application and the chain of command 

The application is the root of the chain of command. If the current command 
object, or bureaucrat, (stored in the global variable gGopher) can’t handle 
a command, it passes the command to its supervisor. If no bureaucrat can 
handle the message, it ends up with the application. If the application 
doesn’t handle a command, the message is ignored. 

Writing the main program 

Your main program must create an application object and assign it to the 
global variable gApplication. After initializing your application, send it 
application a Run message to get it started. Finally, send your application an 
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Exit (or ExitApp in Pascal) message to give it a chance to clean up after 
itself. In THINK Pascal, your main routine should look like this: 


In this example, 
CYourApp is the name of 
your application subclass. 


begin 

new(CYourApp(gApplication)); 
CYourApp(gApplication).IYourApp; 
gApplication.Run; 
gApplication.ExitApp; 
end. 


And in THINK C, your main routine should look like this: 


void main () 

{ 

gApplication = new(CYourApp); 

((CYourApp *)gApplication)->IYourApp(); 
gApplication->Run(); 
gApplication->Exit(); 

} 

Your application subclass must override or define these five methods: 

initialization method (IYourApp in the example) 

OpenDocument 

SetUpFileParameters 

DoCommand 

CreateDocument 


Of course, your subclass can override additional methods if it needs to. 


The term "rainy day fund" 
comes from the expression 
"saving for a rainy day." It 
means to save money in 
case of disaster. 


Handling low memory situations 

The CApplication class provides several methods that deal with low memory 
situations. These methods use a memory reserve called the rainy day fund. 

When you call IApplication, you specify how much memory your appli¬ 
cation should allocate for the rainy day fund. You also specify how many 
bytes of that fund should be available to satisfy Toolbox routine memory re¬ 
quests and how many bytes of that fund should be available to satisfy critical 
operation requests. These values are stored in the instance variables tool- 
boxBalance and criticalBalance. 


If the Macintosh Memory Manager gets a request for more memory than is 
available, it calls a grow zone function. In the THINK Class Library, the grow 
zone function sends the application a GrowMemory message. 

The GrowMemory method tries several strategies to free memory in the 
heap. First, it sends the application a MemoryShort age message. Your ap- 
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plication subclass should override this method to release memory that is not 
crucial to execution. For instance, your Memory Short age method might 
release a code segment it’s not using, or it might dispose of a buffer it no 
longer needs. If the Memory Short age method wasn’t able to release 
enough memory, GrowMemory starts using the rainy day fund. 

GrowMemory looks first at the inCriticalOperation instance variable 
to relase memory from the rainy day fund: 

If inCriticalOperation is leave this much in reserve 

TRUE toolboxBalance 

FALSE criticalBalance 

A critical operation is a temporary operation that takes place in a single Mac¬ 
intosh event, that might take a lot of memory, and that should not cause the 
application to crash. For instance, saving a file is a critical operation. You can 
use the routine SetCriticalOperation to set the inCriticalOper¬ 
ation flag. 

If GrowMemory still wasn’t able to release enough memory and the canFail 
flag is TRUE, GrowMemory returns without trying to allocate any more 
memory. If the canFail flag is TRUE, the application is saying that it can 
deal with a failing memory request. 

If the canFail flag is FALSE, GrowMemory tries to release all the memory 
left in the rainy day fund because the application is not prepared to deal 
with a failing memory request. If there is not enough memory, even after us¬ 
ing the rainy day fund, it is likely that the application will crash. 

You can use the routine SetAllocation to set and reset the canFail 
flag. In general, your application should be prepared to handle failing mem¬ 
ory requests. 

Variables 

The global variable gApplication points to your application object. The 
method I Application sets this variable. 

The instance variables of the application class handle events, memory short¬ 
age situations, standard file parameters, and flow of control. Your applica¬ 
tion subclass may define additional instance variables. 
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Type Description 

CApplication The single instance 

of your application 
object. 

tSystem A global record with 

information about 
the Macintosh and 
System that your 
program is running 
with. 

Only methods of CApplication and its subclasses should use this variable. In 
THINK C, it’s a class variable. 

Variable Type Description 

cMaxSleepTime long default for 

WaitNextEvent 

Event related instance variables 

The event related instance variables handle the interaction between the Mac¬ 
intosh Toolbox Event Manager and your application. Your application sub¬ 
class should not manipulate these variables. 


Variable 

Type 

Description 

itsSwitchboard 

CSwitchboard 

Points to the event- 
processing object. 

itsIdleChores 

CList 

Chores to perform at 
idle time. 

itsUrgentChores 

CCluster 

Chores to perform 
after the current 

event. 

urgentsToDo 

Boolean 

Are any urgent 
chores pending? 

running 

Boolean 

If TRUE, the program 
is still running. 

unhandledTask 

CTask 

Task that no docu¬ 
ment handled 


Global variable 
Variable 

gApplication 

gSystem 


Phase related instance variables 

This variable tells you what phase your application is in. 
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Variable Type Description 

phase integer The phase the application 

is in. 

These are its possible values for phase: 

Value Description 

applnitializing The application is initializing. 

appRuning The application is running. 

appQuitting The application is quitting. 

Memory related Instance variables 

The memory related variables are used when your application is running out 
of memory. The rainyDayFund variable specifies the number of bytes to 


set aside to use when your application runs into a critical memory situation. 

You specify this amount in your application initialization method. 

Variable 

Type 

Description 

rainyDayFund 

Size 

Bytes of memory to 
set aside for critical 
memory situations. 

criticalBalance 

Size 

Portion of rainy¬ 
DayFund to use for 
critical operations. 

toolboxBalance 

Size 

Portion of rainy¬ 
DayFund to use for 
Toolbox operations 
that must not fail. 

tempAllocation 

Size 

Portion of rainy¬ 
DayFund that a rou¬ 
tine has borrowed. 

rainyDay 

Handle 

Handle to the re¬ 
serve memory. 

rainyDayUsed 

Boolean 

Has rainy day fund 
been used? 

memWarninglssued 

Boolean 

Has the user been 
alerted? 

canFail 

Boolean 

Is it OK for memory 
request to fail? 

inCriticalqperation 

Boolean 

Is it OK to use up to 


criticalBalance 
bytes from reserve? 
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Standard file instance variables 

The standard file variables are used in the ChooseFile method as parame¬ 
ters to the Macintosh Toolbox SFPGetFile routine. You set these variables 
in your SetUpFileParameters method. 


Variable 

sfNumTypes 

sfFileTypes 

sfFileFilter 
s fGetDLOGHook 
sfGetDLOGid 

sfGetDLOGFilter 


Type 

integer 

SFTypeList 


DlgHookProcPtr 

integer 


Description 

Number of file 
types recog¬ 
nized 

File types that 
the application 
regognizes 
Filter for files to 
display 
Hook for han¬ 
dling get dialog 
Dialog resource 
ID for get file. 
Default is 
getDlglD 
(-4000). 

Filter for get dia¬ 
log events 


ModalFilterProcPtr 


FileFilterProcPtr 


Methods 

The methods of the CApplication class deal with application initialization 
and document handling. Since the application is the ultimate supervisor for 
all the command objects, it also serves as the end of the chain of command. 

Initialization methods 

The initialization methods set up the application’s memory and file parame¬ 
ters. Your application subclass should implement its own initialization meth¬ 
od and call the default initialization method. 

(Application procedure IApplication (extraMasters: integer; 

aRainyDayFund, aCriticalBalance, 
aToolboxBalance: Size); 

void IApplication (short extraMasters, 

Size aRainyDayFund, Size aCriticalBalance, 

Size aToolboxBalance); 

This is the main initialization method. In your application subclass, you 
should implement a method called I MyAppClass, where MyAppClass is the 
name of your application subclass. 
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InltMemory 
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The extraMasters, aCriticalBalance, and aToolboxBalance pa¬ 
rameters are passed to the InitMemory method described later on. 

Your application subclass must call CApplication. IApplication (in 
THINK Pascal) or CApplication: : IApplication (in THINK C) in its 
initialization method. If your application subclass defines instance variables, 
your initialization method should initialize the variables. 

This method also initializes these global variables. All the global variables 
are described in detail in Chapter 72, “Global Variables.” 


gApplication 

gSleepTime 

gWatchCursor 

gGopher 

gClicks 


gSignature 

gIBeamCursor 

gUtilRgn 

gLastViewHit 

gSystem 


Finally, this method sends the following messages to your application ob¬ 
ject. The rest of this section goes into detail for each method. 


InitToolbox 

InspectSystem 

MakeSwitchboard 

MakeDesktop 

MakeDecorator 

SetUpMenus 


InitMemory 

InstallPatches 

MakeError 

MakeClipboard 

SetUpFileParameters 


procedure InitToolbox; 
void InitToolbox (void); 

This method initializes all of the Macintosh Toolbox managers. Your applica¬ 
tion subclass should not need to override this method. 


procedure InitMemory (extraMasters: integer; 
aRainyDayFund, aCriticalBalance, 
aToolboxBalance: Size); 

void InitMemory (short extraMasters, 

Size aRainyDayFund, Size aCriticalBalance, 

Size aToolboxBalance); 

This method initializes the Macintosh memory manager and sets up the 
GrowZone function used in low memory situations. ExtraMasters is the 
number of times to call the Toolbox routine MoreMasters. ARainyDay¬ 
Fund is the number of bytes to set aside in the application heap to deal with 
low memory situations. ACriticalBalance is the number of bytes to use 
from the rainyDayFund for critical operations. AToolboxBalance is the 


Object-Oriented Programming 14 3 


^ 7 7 CApplication __ 

number of bytes to use from the rainyDayFund for Toolbox operations 
that can’t fail. 

ARainy Day Fund must be greater than or equal to aCritical Balance, 
and aCriticalBalance must be greater than aToolboxBalance. 

The values that you use as arguments to this method depend on the memory 
requirements of your application. You can use these values to get started: 

Argument Suggested value 

extraMasters 10 

aRainyDayFund 45000 

aCriticalBalance 40000 

aToolboxBalance 20000 

MakeS witch board procedure MakeSwitchboard; 

void MakeSwitchboard (void); 

This method creates the application’s switchboard and stores it in the in¬ 
stance variable itsSwitchboard. If you create your own subclass of 
CBartender, you should override this method in your application subclass. 

MakeError procedure MakeError; 

void MakeError (void); 

This method creates the error-handler and stores it in the global variable 
gError. If you create your own error-handler, you can create a subclass of 
CError and override this method to use your error-handler. 

procedure MakeDesktop; 
void MakeDesktop (void); 

This method creates the desktop and stores it in the global variable 
gDesktop. The default method creates the standard desktop CDesktop. If 
your application uses a non-standard desktop, such as CFWDesktop, you 
should override this method in your application subclass. 

MakeClipboard procedure MakeClipboard; 

void MakeClipboard (void); 

This method creates the clipboard and stores it in the global variable 
gClipboard. If you create your own subclass of CClipboard, you should 
override this method to create a clipboard of your class. 


MakeDesktop 

CFWDesktop, which imple¬ 
ments a desktop with float¬ 
ing windows, is described 
on page 289. 
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procedure MakeDecorator; 
void MakeDecorator (void); 

This method creates the window decorator and stores it in the global vari¬ 
able gDecorator. The window decorator is responsible for the default siz¬ 
es of windows and arranges them neatly on the desktop. If you want to 
implement a different decorator, you can create a subclass of CDecorator 
and override this method to use your decorator. 

procedure SetUpFileParameters; 
void SetUpFileParameters (void) ; 

This method lets you set up the parameters that specif/ what kinds of files 
your application works on. The THINK Class Library passes some of these 
parameters to the Toolbox SFPGetFile function which displays the stan¬ 
dard get file dialog. Your application subclass should override this method 
and call the inherited method to set up the default values. 

Your own method should set the following instance variables and globals: 


sfNumTypes 

sfFileTypes 

gSignature 

sfFileFilter 

sfGetDLOGHook 
sfGetDLOGid 

sfGetDLOGFilter 


The number of different types of files your 
application deals with. If your application 
can open any kind of file, use -1. 

The file types of the files that your applica¬ 
tion deals with. One type for each element 
of this array. 

The four-character signature of your appli¬ 
cation. Although it’s not an instance vari¬ 
able, this method is the place to set up this 
global variable. 

Optional. A pointer to a function that fil¬ 
ters the file names your application can 
deal with. 

Optional. A pointer to a dialog hook func¬ 
tion for the standard get file dialog. 
Optional. The resource ID of the standard 
get file dialog you’re using. Do not change 
this variable if you want to use the default 
dialog 

Optional. A pointer to a dialog filter proc 


To learn about file filter functions, dialog hook functions, and dialog filters, 
see Inside Macintosh /, Chapter 20, “The Standard File Package. ” 
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♦ 

SetUpMenus 


MakeBartender 


InspectSystem 


procedure SetUpMenus; 
void SetUpMenus (void) ; 

SetUpMenus calls MakeBartender and reads all the menu information 
from your application’s MBAR 1 resource and builds the menus. It also 
builds the desk accessory menu. 

If your application uses menus that need to be built on the fly, you should 
override this method. For instance, if your application uses a Font menu, 
you would build it in this method. Be sure to call inherited 
SetUpMenus to make sure all the regular menus get built. See the descrip¬ 
tion of CBartender, especially section “Resource based menus” on page 168, 
for more information about building these kinds of menus. 

procedure MakeBartender; 
void MakeBartender (void); 

This method creates the bartender object, which handles all interactions 
with the menu bar and menu items, and stores it in the global variable 
gBartender. If you create your own subclass of CBartender, you should 
override this method in your application subclass. 

procedure InspectSystem; 
void InspectSystem (void); 

This method fills in the fields of the gSystem global variable which gives you 
information about the Macintosh and the System Software that your applica¬ 
tion is running under. 

In THINK C, tSystem is declared like this: 


typedef struct 
/ 

i 

Boolean 

hasWNE : 

Boolean 

hasColorQD : 

Boolean 

hasGestalt : 

Boolean 

hasAppleEvents : 

Boolean 

hasAliasMgr : 

Boolean 

hasEditionMgr : 

Boolean 

hasHelpMgr : 

Boolean 

hasScriptMgr : 

Boolean 

hasFPU : 

short 

scriptsinstailed 

short 

systemVersion; 

} tSystem; 
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InstallPatches 


ForceClassReferences 
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In THINK Pascal it’s defined like this: 
type 

tSystem = packed record of 
hasWNE, 
hasColorQD, 
hasGestalt, 
hasAppleEvents, 
hasAliasMgr, 
hasEditionMgr, 
hasHelpMgr, 
hasScriptMgr, 

hasFPU : Boolean; 

scriptsinstailed, 
systemVersion : integer- 

end; 

The field scriptslnstalled tells you how many scripts are in use. The 
field systemVersion gives you the version of the Macintosh System that’s 
running. The version number is given as two byte-long numbers. For exam¬ 
ple, if systemVersion is 0x0607, the System version number is 6.0.7. 

Advanced initialization methods 

You should not need to override these methods. If you are an advanced 
Macintosh programmer, you may want to take advantage of the fact that 
they’re called in IApplication. 

procedure InstallPatches; 
void InstallPatches (void); 

Install patches to Toolbox routines. The default method patches Loads eg 
to make sure that CODE resources can be loaded. If a code resource can’t be 
loaded, the patch raises an exception. The default method also patches 
ExitToShell to call RemovePatches. 

procedure RemovePatches; 
void RemovePatches (void); 

Remove the Toolbox patches made in InstallPatches. 

procedure ForceClassReferences; 
void ForceClassReferences (void) ; 

If there are classes in your application that are instantiated by name, add a 
dummy reference to them here to prevent the smart linker from stripping 
them out. 
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♦ 

CetPhase 


Notify 

DoKeyDown 

DoAutoKey 


Accessing methods 

function GetPhase: integer; 
short GetPhase (void); 

Return current application phase. The possible values are 
applnitializing, appRunning, and appQuiting. 

Command methods 

The command methods handle events that the application takes care of. 
Since messages frequently get passed up the chain of command— from the 
pane, to the document, to the application— the application is the last chance 
to handle command messages. Most of the command methods don’t do any¬ 
thing. They’re null methods that keep the message from being passed on. 

procedure Notify (theTask: CTask); 
void Notify (CTask *theTask); 

When a subordinate object finishes a task, it sends the task to its supervisor. 
Documents usually handle Notify messages. This method is here in case a 
document tries to pass the Notify message on to the application. It places 
theTask into the instance variable unhandledTask. The task is disposed 
of at the end of the current event. 

procedure DoKeyDown (theChar: char; keyCode: Byte; 
macEvent: EventRecord); 

void DoKeyDown (char theChar, Byte keyCode, 

EventRecord *macEvent); 

You should handle key-down events within a pane or a document. For ap¬ 
plications, this method doesn’t do anything. It’s here in case the 
DoKeyDown message gets passed up the chain of command. Your applica¬ 
tion subclass should not override this method. 

procedure DoAutoKey (theChar: char; keyCode: Byte; 
macEvent: EventRecord); 

void DoAutoKey (char theChar, Byte keyCode, 

EventRecord *macEvent); 

You should handle auto-key events within a pane or a document. For appli¬ 
cations, this method doesn’t do anything. It’s here in case the DoAutoKey 
message gets passed up the chain of command. Your application subclass 
should not override this method. 
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DoKeyUp 


procedure DoKeyUp (theChar: char; keyCode: Byte; 
macEvent: EventRecord); 

void DoKeyUp (char theChar, Byte keyCode, 

EventRecord *macEvent); 

You should handle key-up events within a pane or a document. For applica¬ 
tions, this method doesn’t do anything. It’s here in case the DoKeyUp mes¬ 
sage gets passed up the chain of command. Your application subclass 
should not override this method. 


Note 

The Macintosh system event mask is usually set to mask out 
key-up events. If you need to get key-up events, be sure to 
reset the system event mask with the Toolbox routine 
SetEventMask. 


DoCommand 


procedure DoCommand (theCommand: longint); 
void DoCommand (long theCommand); 

This is the only application command method that really does anything. Do¬ 
Command handles application commands that the user chooses from the 
menu. These are the commands that the default DoCommand method han¬ 
dles: 


Command 

cmdNew 

cmdOpen 


cmdClose 


cmdQuit 


Action 

Sends a CreateDocument message to 
the application. 

Sends a ChooseFile message to your 
application. If the reply is good, sends an 
OpenDocument message to your applica¬ 
tion. The default ChooseFile message 
calls SFPGetFile with the values you 
specified in the 

SetUpFileParameters method. Your 
application must override the 
OpenDocument method. 

If the front window is a desk accessory, 
close it. Your document class should han¬ 
dle this command to close documents. 
Sends a Quit message to your applica¬ 
tion. The default Quit method sends a 
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Quit message to the supervisor (a direc¬ 
tor) of each open window 

cmdUndo 

cmdCut 

cmdCopy 

cmdPaste 

cmdC 1 e a r If the front window is a desk accessory, al¬ 

ways call SystemEdit. Your document 
class should handle these commands to 
edit documents. 

cmdToggleClip Sends a Toggle message to the clip¬ 

board. 

If your application defines its own application-related events, your applica¬ 
tion class should override this method. If your DoCommand method gets a 
command that it does not handle, it should call inherited DoCommand. 

UpdateMenuS procedure UpdateMenus; 

void UpdateMenus (void); 

This method enables the appropriate menu items right before a menu selec¬ 
tion. The default method enables the Quit command. If the application is in 
the foreground, it enables the Show/Hide Clipboard command. If the ap¬ 
plication is in the background, this method enables the cmdClose, 
cmdUndo, cmdCut, cmdCopy, cmdPaste, and cmdClear commands for 
desk accessories. 

Your document’s UpdateMenus method should enable the appropriate 
Edit menu commands for the document 

PackageAppleEvent function PackageAppleEvent ( 

theEvent, theReply: AppleEvent; long theRefCon; 
eventClass, eventID: DescType): CAppleEvent; 

CAppleEvent ^PackageAppleEvent ( 
struct AppleEvent *theEvent, 

struct AppleEvent *theReply, long theRefCon, 
DescType eventClass, DescType eventID); 

Package an incoming AppleEvent and its default reply into a CAppleEvent 
object. This method returns a CAppleEvent object of class. If you create a 
sublcass of CAppleEvent, you need to override this class. CAppleEvent is de¬ 
scribed on page 131. 
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DoAppleEvent 


RequestMemory 
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procedure DoAppleEvent (anAppleEvent: CAppleEvent); 
void DoAppleEvent (CAppleEvent *anAppleEvent); 

Respond to an AppleEvent. This method handles the four required Ap- 
pleEvents: kAEOpenApplication, kAEOpenDocuments, 
kAEPrintDocuments, and kAEQuitApplication. If you create a subl- 
cass of CAppleEvent, you need to override this class. CAppleEvent is de¬ 
scribed on page 131. 

Memory management methods 

These methods deal with critical memory situations in your application. The 
InitMemory method sets the function GrowZoneFunc as the function to 
call in low-memory situations. This function sends a GrowMemory message 
to your application to try to reclaim enough memory to continue. 


Note 

GrowZoneFunc is defined in TCL. p in THINK Pascal and 
in CError. h in THINK C. 


procedure RequestMemory (aCanFail: Boolean); 
void RequestMemory (Boolean aCanFail); 

Change the canFail instance variable which controls how GrowMemory 
releases memory from the rainy day fund. If aCanFail is FALSE, the Grow¬ 
Memory method is more conservative about releasing memory for a failing 
memory request. If aCanFail is TRUE, GrowMemory will exhaust the rainy 
day fund to satisfy the request. 

Instead of using this method, you should use the utility routine 
Set Allocation (described on page 466). Set Allocation sends a 
RequestMemory message to the application and returns the previous val¬ 
ue, so you can set it back. 

Here’s an example, in THINK Pascal: 
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procedure AClass.AMethod; 
var 

oldAlloc: Boolean; 
myHandle: Handle; 

begin 

oldAlloc := SetAllocation(TRUE); 
myHandle := NewHandle(50000); 

SetAllocation(oldAlloc); 

if myHandle := nil then 
begin 

couldn’t get 50000 bytes 

end 

else 

begin 

Go on with this operation 

end 

end; 

And here’s the same example in THINK C: 

void AClass::AMethod(void); 

{ 

Boolean oldAlloc; 

oldAlloc = SetAllocation(TRUE); 
myHandle = NewHandle(50000L); 

SetAllocation(oldAlloc); 

if (myHandle == NULL) { 
couldn’t get 50000 bytes 

} 

else { 

Go on with this operation 

} 

} 

Remember that if the argument you pass to SetAllocation or Request- 
Memory is FALSE, GrowMemory will do whatever it can to get the memory. 
If there still isn’t enough memory after the rainy day fund has been exhaust¬ 
ed, your program will probably crash. 

SetCriticalOperation procedure SetCriticalOperation (isCritical: Boolean); 

void SetCriticalOperation (Boolean isCritical); 

Set the inCriticalOperation instance variable which controls how 
GrowMemory releases memory from the rainy day fund. If inCriticalOpera- 
tion is TRUE, and there is a memory shortage that causes GrowMemory to be 
called, grow memory tries to release as much memory in the rainy day fund 
that would leave toolboxBalance bytes free. 
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GrowMemory 


MemoryShortage 
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Your application should call the utility routine SetCriticalOperation 
(described on page 467) instead of sending a SetCriticalOperation 
message to gApplication. 

Use this routine when there is a operation that must complete and for which 
your application might need to use some of the memory in the rainy day 
fund. The critical operation should release any memory that it allocated. 

For example, when your application is saving a file, you may need to allo¬ 
cate an extraordinary amount of memory. In this case, you would call Set¬ 
CriticalOperation to let GrowMemory know that, if necessary, you’re 
willing to use more of the rainy day fund. Once the operation is complete, 
you would dispose of the memory. 

Note that the Run method resets inCriticalOperation to FALSE every 
time through the event loop. 

function GrowMemory(bytesNeeded: Size): longint; 
long GrowMemory (Size bytesNeeded); 

The GrowZoneFunc function that the Memory Manager calls in low memo¬ 
ry situations invokes this method to try to reclaim memory. GrowMemory 
sends a MemoryShortage message to the application. 

If Memory Short age wasn’t able to release enough memory, GrowMemory 
starts to use the rainy day fund. If inCriticalOperation is TRUE, it uses 
as much of the rainy day fund that would still leave toolboxBalance 
bytes in the fund. If inCriticalOperation is FALSE, it uses as much that 
would leave citicalBalance bytes in the fund. 

If GrowMemory still wasn’t able to release enough memory from the rainy 
day fund, and canFail is FALSE, the entire rainy day fund is released. If the 
entire rainy day fund has been exhausted, this method calls OutOfMemory. 

procedure MemoryShortage (bytesNeeded: Size); 
void MemoryShortage (Size bytesNeeded); 

The GrowMemory method sends a MemoryShortage message to your ap¬ 
plication to try to free memory. The default MemoryShortage method 
does nothing, so your application subclass should override this method. 
Your MemoryShortage method should try to free bytesNeeded bytes of 
memory, and it should disable menu commands that won’t work in low 
memory situations. 
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Warning 

Your MemoryShortage method must not allocate any 
memory. 


MemoryReplenished procedure MemoryReplenished; 

void MemoryReplenished (void); 

Your application will get this message when the memory situation is no 
longer critical. The default MemoryReplenished method does nothing, so 
your application subclass should override this method. Your 
MemoryReplenished method should enable the commands you disabled 
in the Memory Short age method. You might also want to reallocate memo¬ 
ry that you released in that method. 

OutOfMemory function OutOfMemory (bytesNeeded: Size) : longint; 

long OutOfMemory (Size bytesNeeded); 

A memory request cannot be satisfied, and canFail was FALSE, so the ap¬ 
plication won’t handle the memory allocation failure. This method calls 
Failure (memFullError, 0). If there is any memory left, the top-level 
handler will display an alert, but it is more likely that the application will 
crash. 

You can override this method if you can free up more memory, or if you can 
exit the application gracefully without allocating memory. Normally, you 
would try to free enough memory in your Memo ryShortage method. If 
there are more drastic ways to release memory, implement them here. This 
method should return 1 if it successfully released memory or zero if it 
couldn’t. 


Warning 

This method should not allocate any memory or call any 
routines that allocate memory. 


Execution methods 

The execution methods are invoked while your application is running. Most 
of these methods handle system-related events. The only execution method 
your application should override is the Exit method. 

Run procedure Run; 

void Run (void); 

This method runs your application until the user quits. This method sends 
the application Proces si Event messages until the user chooses to quit. 
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Processl Event 


Preload 


StartUpActlon 


Suspend 


Resume 


♦ 


Before running your program, this method sends a Preload message to 
your application to open or print documents that the user selected and 
opened from the Finder. 

Your application should not override this method. 

procedure ProcesslEvent; 
void ProcesslEvent (void); 

Process and dispatch one event. This method sends a ProcessEvent mes¬ 
sage to the switchboard (stored in the instance variable 
itsSwitchboard). If you installed an urgent chore, this method sends it a 
Perform message. 

procedure Preload; 
void Preload (void); 

If the user opened or chose to print files from the Finder, this method sends 
the application an OpenDocument message for each document. If the user 
chose the Print command, this method sends a DoCommand (cmdPrint) 
message to the gopher. After processing all the files, this method sends the 
application a StartUpAction message. 

procedure StartUpAction (numPreloads: integer); 
void StartUpAction (short numPreloads); 

This method gives you an opportunity to perform any startup actions. 
NumPreloads is the number of files that the user selected from the Finder. 
If numPreloads is zero, the default method sends a 
DoCommand (cmdNew) message to the gopher (usually the application). 
The effect of the default method is to open an untitled document at startup. 

procedure Suspend; 
void Suspend (void); 

Your application is about to be suspended under MultiFinder. The default 
method calls the inherited method and sets the global variable glnBack- 
ground to TRUE. 

procedure Resume; 
void Resume (void); 

Your application has come back to the foreground under MultiFinder. The 
default method calls the inherited method and sets the global variable gln- 
Backgroundto FALSE. 
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SwItchToDA 

SwitchFromDA 

Idle 


Quit 


ExIt/ExItApp 


procedure SwitchToDA; 
void SwitchToDA (void) ; 

A desk accessory is becoming active. The default method sends the applica¬ 
tion a Suspend message. Your application should not override or use this 
method. 

procedure SwitchFromDA; 
void SwitchFromDA (void) ; 

Your application is becoming active after a desk accessory was active. The 
default method sends your application a Resume message. Your application 
should not override or use this method. 

procedure Idle (macEvent: EventRecord); 
void Idle (EventRecord *macEvent); 

This method handles periodic tasks. It also checks to see if a critical memory 
situation is no longer critical. Idle sends Dawdle messages to the gopher 
and to each of the gopher’s supervisors. It also sends Perform messages to 
all chores. Your application should not override this method. 

procedure Quit; 
void Quit (void); 

The user wants to quit the application. This method sends a Quit message 
to the supervisor (a director) of each open window. Any of the directors can 
cancel quitting. Your application should not override this method. 


Note 

The Quit method for directors returns a Boolean value. If 
it returns FALSE, quitting is canceled. 


procedure ExitApp; 
void Exit (void); 

The application is about to exit. Your main program should send an Exit 
message to the application before it terminates; the THINK Class Library will 
not send the message for you. The default method does nothing. 

The Exit method is the last chance you have to clean up after your applica¬ 
tion. For example, this is a good place to delete any temporary files you’ve 
created. 
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JumpToEventLoop 


CreateDocument 


OpenDocument 


ChooseFile 
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procedure JumpToEventLoop; 
void JumpToEventLoop (void); 

This method is for compatibility with earlier versions of the THINK Class Li¬ 
brary. It callse Failure (kSi lent Err, 0) to force a return to the top- 
level exception handler in Run. 

Document methods 

The document methods of an application deal with creating and opening 
documents. In your application subclass, the only document methods you’ll 
need to override are CreateDocument and OpenDocument. All the other 
document methods are used internally to implement standard behavior. 

procedure CreateDocument; 
void CreateDocument (void); 

This method creates a new document. The default Do Command method 
sends a CreateDocument message to the application when the user 
chooses New from the File menu. Your application must override this meth¬ 
od. Your CreateDocument method needs to create a new document, ini¬ 
tialize it, and then send it a NewFile message. 

procedure OpenDocument (macSFReply: SFReply); 
void OpenDocument (SFReply *macSFReply); 

This method opens an existing document. The macSFReply record speci¬ 
fies which document to open. The default DoCommand method sends an 
OpenDocument message to the application when the user chooses 
Open... from the File menu. 


Note 

DoCommand actually sends a ChooseFile message to the 
application first, and if the reply is good, it sends an 
OpenDocument message. Your OpenDocument method 
can assume that the macSFReply record is valid. 


Your application subclass must override this method. Your OpenDocument 
method needs to create a new document, initialize it, and then send it an 
OpenFile (macSFReply) message. 

procedure ChooseFile (var macSFReply: SFReply); 
void ChooseFile (SFReply *macSFReply); 

This method displays a standard get file dialog and places the reply in the 
macSFReply record. This method calls the Toolbox routine SFPGetFile 
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with the file parameters you specified in the SetUpFileParameters 
method. 

You can send the application a ChooseFile message from other methods 
to get the name and location of a file. Don’t forget to check the 
macSFReply. good field to make sure that the information in the record is 
valid. 

Your application subclass should not override this method unless it uses a 
different technique to open a document. 

Periodic task methods 

procedure AssignldleChore (theChore: CChore); 
void AssignldleChore (CChore *theChore); 

This method adds theChore to the application’s list of chores. The applica¬ 
tion sends a Perform message to each chore at idle time. Your application 
should not override this method. 

Note 

If you want to remove the chore from the list later on, you 
must keep a pointer to the chore object. 

CancelldleChore procedure CancelldleChore (theChore: CChore); 

void CancelldleChore (CChore *theChore); 

This method removes theChore from the application’s list of chores. Your 
application should not override this method. 

AssignUrgentChore procedure AssignUrgentChore (theChore CChore) ; 

void AssignUrgentChore (CChore *theChore); 

This method adds theChore to the application’s list of urgent chores. The 
application sends a Perform message to each urgent chore after handling 
the current event and then removes the chore. Your application should not 
override this method. 

Class resources 

Resource Description 

MBAR 1 The application’s menu bar 

STR# 129 Low memory warning strings. 


AssignldleChore 


158 Object-Oriented Programming 




Introduction 

CArray implements a resizable array. 

Heritage 

Superclass CCollection 

Subclasses CCluster 

CRunArray 

Using CArray 

Use CArray when you want an array you can resize. The elements may be 
any size, as long as they’re all the same size. 

To insert a new element into the array, use Insert At Index. It moves the 
element in that slot and all the element below it down one slot. It’s illustrat¬ 
ed in Figure 12-1. 



Figure 12-1 Before and after InsertAtlndex 
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To update the value of an existing element, use Set Item. It at that slot with 
the new element. It’s illustrated in Figure 12-2. 



Figure 12-2 Before and after Setltem 


To delete an element, use Dele tel tern It deletes the element and moves 
all the elements below it up one slot. 

CArray stores the elements in its array in one large piece of memory that it al¬ 
locates dynamically. It uses the instance variable blockSizeto control 
how to grow and shrink this memory. If there are no empty slots when you 
try to insert an element, CArray grows memory byblockSize slots. When 
you delete an element and there are blockSize empty slots left, CArray 
shrinks the memory by blockSize slots. By default, blockSize is 3. 

CArray has two methods that move elements in the array: Swap and 
Move I temTo Index. To store an element while moving it, CArray has a 
temporary storage slot at the end of the array. To make sure an element in 
temporary storage isn’t accidently overwritten, those methods set the flag 
usingTemporary whenever they put something in the temporary storage 
slot. This slot is not counted in the slots instance variable, which is the to¬ 
tal number of slots that can permanently store elements. 
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lArray 


Free/Dispose 


SetBlockSize 


SetLockChanges 
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Variables 



Variable 

Type 

Description 

blockSize 

integer 

Number of slots to 
allocate when more 
space is needed. 

slots 

longint 

Total number of slots 
allocated. 

hltems 

Handle 

Items in the array 

elementSize 

longint 

Size of each element 
in bytes 

lockChanges 

Boolean 

If TRUE, you can’t in¬ 
sert or delete in ar¬ 
ray. 

usingTemporary 

Boolean 

If TRUE, temporary 
element storage 
buffer is in use. 


Methods 

Creation and destruction methods 

procedure IArray (elementSize: longint); 
void IArray (long elementSize); 

Initialize the array. Element Si ze is the size of each element in the array. 
This method sets the size of each element in the array to ElementSize, 
sets blockSize to 3, and allocates enough space for the temporary storage 
slot. 

procedure Free; 
void Dispose (void); 

Dispose of the array and the block of memory it allocated. 

Accessing methods 

procedure SetBlockSize (aBlockSize: integer); 
void SetBlockSize (short aBlockSize); 

Set the number of elements to add to the array when CArray allocates more 
space. IArray initializes this value to 3. 

function SetLockChanges (fLockChanges: Boolean): 
Boolean; 

Boolean SetLockChanges (Boolean fLockChanges); 

If f LockChanges is TRUE, you can’t use the Insert At Index and 
Deleteltem methods. This method sets lockChanges to 
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InsertAtlndex 


Deleteltem 


Setltem 


Store 


Getltem 


f LockChanges and returns the previous value of lockChanges. CCluster 
uses this method to prevent you from corrupting the array when you iterate 
over its elements with DoForEarch. 

Insertion and deletion methods 

procedure InsertAtlndex (itemPtr: Ptr; 
index: longint); 

void InsertAtlndex (void *itemPtr, long index); 

Insert the element at itemPtr at the index index. If index is already oc¬ 
cupied, move the element in that slot and all the element below it down one 
slot. If index is beyond the last position, add the item to the end of the ar¬ 
ray. If necessary, this method allocates a larger block of memory for the ar¬ 
ray. This method sends a BroadcastChange message with 
arraylnsertElement as the reason. 

procedure Deleteltem (index: longint); 
void Deleteltem (long index); 

Delete the element at index index. This method moves all the elements be¬ 
low index up one slot. If the number of free slots is greater than 
blockSize, this method reallocates a block of memory that’s smaller by 
blockSize slots. 

procedure Setltem (itemPtr: Ptr; index: longint); 
void Setltem (void *itemPtr, long index); 

Put the element at itemPtr into the array at position index. Index must 
be within the array. This method sends a BroadcastChange message with 
arrayElementChanged as the reason. 

procedure Store (itemPtr: Ptr; index: longint); 
void Store (void *itemPtr, long index); 

Put the element at itemPtr into the array at position index. Whenever 
possible, use Set instead. This is an internal method that performs no error- 
checking. In THINK C, this is a protected method. 

Membership method 

procedure GetITem (itemPtr: Ptr; index: longint); 
void Getltem (void *itemPtr, long index); 

Return the element at position index in the block memory at itemPtr. 
Index must be within the array. ItemPtr must point to a block large 
enough to hold one element. 
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Retrieve 


Search 


MoveltemToIndex 


Swap 
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procedure Retrieve (itemPtr: Ptr; index: longint); 
void Retrieve (void *itemPtr, long index); 

Return the element at position index in the block memory at itemPtr. 
Whenever possible, use Get instead. This is an internal method that per¬ 
forms no error-checking. In THINK C, this is a protected method. 

function Search (itemPtr: Ptr; function compare ( 
iteml, item2: Ptr) : integer) : Ptr; 

void ^Search (void *itemPtr, CompareFunc compare); 

Find an element that satisfies a condition. The function compare tests for 
the condition. It takes two arguments. The first is itemPtr and the second 
is a pointer to an element in the array. Compare should return 0 when an el¬ 
ement satisfies the condition. ItemPtr is a pointer to some data that you 
can use in the comparison. It can be a pointer to data like that in the array, a 
pointer to another type of data, or NIL 

In THINK C, declare compare like this: 

int compare (void *iteml, void *item2); 

In THINK Pascal, declare compare like this: 

function compare (iteml, item2: Ptr): integer; 

Moving methods 

procedure MoveltemToIndex (currentlndex, newlndex: 
longint); 

void MoveltemToIndex (long currentlndex, 
long newlndex); 

Move the element at currentlndex to newlndex. This method moves 
the elements between the old and new positions up or down slot. This 
method sends a BroadcastChange message with arrayMoveElement 
as the reason. 

procedure Swap (indexl, index2: longint); 
void Swap (long indexl, long index2); 

Swap the two items: move the item at indexl to index2, and move the 
item at index2 to indexl. For both items, this method sends a 
BroadcastChange message with arrayElementChanged as the rea¬ 
son. 
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Resize 


MoreS lots 


CopyToTemporary 


CopyFromTemporary 


ItemOffset 


Resizing methods 

CArray uses these internal methods to resize its block of memory. You 
should need to use them only if you are creating a subclass of CArray. In 
THINK C, only subclasses of CArray can use them. 

procedure Resize (numSlots: longint); 
void Resize (long numSlots); 

Resize the array so that it has numSlots slots. This method does not change 
the number of items stored in the array. 

procedure MoreSlots; 
void MoreSlots (void); 

Add blocksize slots to the array. 

Temporary storage methods 

CArray uses these methods to move elements into and out of the temporary 
storage slot. You should need to use them only if you are creating a subclass 
of CArray. In THINK C, only subclasses of CArray can use them 

procedure CopyToTemporary (index: longint); 
void CopyToTemporary (long index); 

Place the element in slot index into temporary storage. This method also 
sets usingTemporary to TRUE. 

procedure CopyFromTemporary (index: longint); 
void CopyFromTemporary (long index); 

Place an item from temporary storage into slot index. This method also sets 
usingTemporary to FALSE. 

Offset method 

CArray uses this method to find the offset into the array of an element. You 
should need to use it only if you are creating a subclass of CArray. In THINK 
C, only subclasses of CArray can use it. 

function ItemOffset (itemlndex: longint) : longint; 
long ItemOffset (long itemlndex); 

Return the offset into the array of the slot itemlndex in bytes. 
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Introduction 

The bartender is the object that manages the menu bar, menus, and menu 
items. The bartender is an object of class CBartender. There is only one ob¬ 
ject of this class stored in a global variable. 


Note 

Earlier versions of the THINK Class Library used CBarOwn- 
er, a subclass of CBartender, to prevent excessive menu bar 
flashing. This version of CBartender includes this improve¬ 
ment. 


Heritage 

Superclass CObject 

Subclasses This class has no subclasses. 

Using CBartender 

In the THINK Class Library, almost every menu item has a command number 
associated with it. The bartender maintains a table that maps menu items 
with command numbers. You should never try to access the bartender’s data 
structures directly. Instead, use the access methods. 

You should not need to subclass the CBartender class. If, for some reason, 
you do need to create a subclass, you’ll also need to override the 
SetUpMenus method in your application class to initialize your bartender. 

To manipulate the menus or menu items, send messages to the global bar¬ 
tender object stored in the global variable gBartender. 

Creating standard menus 

To associate a command number with a menu item, append the command 
number to the end of the menu item in your MENU resource. The menu item 
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text and the command number are separated by the character #. Figure 13-1 
shows what the File menu looks like in ResEdit: 


|in . ; MENU “File” ID = 2 from TCL Resources m \ 


File 

Entire Menu: E3 Enabled 

Title: ® File 

Nem#2 

Open... #3 

z o 

Qp QA 

w w 

■ 

mil 

Close#4 

86 111 

lljljj 

«... 

O 6 (Rpple menu) 

Saue#5 

96S 



Saue Rs...#6 


Ill 

Color 

Reuert to Saued#7 


flflii 

Tltle: BB 

Page Setup...#8 


II 

Item TeHt Default: |^| 

Print...#9 

86P 

1 

Menu Background: | | 


Figure 13-1 The File menu in ResEdit 


If you don’t append a command number to a menu item, the bartender auto¬ 
matically associates the command number cmdNull with it. 

The bartender builds its tables from the information in the MBAR resource 
you pass to its initialization method Your application’s MBAR resource 
should contain the menu IDs of all the menus that will appear in the menu 
bar. 


Note 

By default, the application’s SetUpMenus method uses the 
MBAR resource with an ID = 1. 


Th e MENU resources for 
these menus are in the file 
TCL Resources. 


You can use any menu ID for your application’s menus. The THINK Class Li¬ 
brary reserves the following menu IDs for certain menus: 


Menu title 

Apple 

File 

Edit 

Font 

Size 


Menu ID 

1 

2 

3 

10 

11 


Mnemonic 

MENUapple 
MENUfile 
MENUedit 
MENUfont 
MENUsize 
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These are the commands that the THINK Class Library defines. In THINK 
Pascal they’re in the TCL. p, and in THINK C they’re in the file 
Commands. h. Remember that the THINK Class Library reserves the com¬ 
mands in the range 1 to 1023. 

These are standard File menu commands: 


Command ID 

cmdQuit 1 

cmdNew 2 

cmdOpen 3 

cmdClose 4 

cmdSave 5 

cmdSaveAs 6 

cmdRevert 7 

cmdPageSetup 8 

cmdPrint 9 

These are the standard Edit menu commands: 

Command ID 

cmdUndo 1 6 

cmdCut 18 

cmdCopy 19 

cmdPaste 20 

cmdClear 21 

cmdToggleClip 22 

cmdSelectAll 23 

These are the text style commands: 

Command ID 

cmdPlain 30 

cmdBold 31 

cmdltalic 32 

cmdUnderline 33 

cmdOutline 34 

cmdShadow 35 

cmdCondense 36 

cmdExtend 37 
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These are the text alignment commands: 


Command ID 

cmdAlignRight 40 
cmdAlignLeft 41 
cmdAlignCenter 42 
cmdJustify 43 


These are the line spacing commands: 

Command ID 

cmdSingleSpace 50 

cmdlHalf Space 51 

cmdDoubleSpace 52 

These are miscellaneous commands: 


Command 

ID 

Description 

cmdNull 

0 

Command which does 
nothing 

cmdOK 

100 

OK button in dialog box 

cmdCancel 

101 

Cancel button in dialog 
box 

cmdAbout 

256 

About Application request 


If you want the bartender to return the menu ID and item number of a par¬ 
ticular menu item, use the special command -1 in your MENU resource. The 
bartender will return the negative of the menu ID in the high word and the 
menu item number in the low word. This is the same as menus that you 
build on the fly, described next. 

Resource based menus 

Your application may use menus that don’t have menu commands associat¬ 
ed with each item. The most common example is a Font menu. Use the re¬ 
served Font menu in your MBAR resource, and add the resources with the 
AddResMenu Toolbox routine. Here’s how you might write your 
SetUpMenus method in THINK Pascal to include a font menu. 

procedure CYourApp.SetUpMenus; 
begin 

inherited SetUpMenus; 

AddResMenu(GetMHandle(MENUfont), 'FONT'); 

SetDimOption(MENUfont, dimNONE); 

SetUnchecking(MENUfont, true); 
end; 
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And here’s how you might write your the method in THINK C: 

void CYourApp::SetUpMenus() 

{ 

MenuHandle macMenu; 
inherited::SetUpMenus(); 

AddResMenu(GetMHandle(MENUfont), 'FONT'); 

SetDimOption(MENUfont, dimNONE); 
SetUnchecking(MENUfont, TRUE); 


Note 

To learn about SetDimOption and SetUnchecking, 
see section “Dimming and checking menu items” on page 
171. 


When you build a menu on the fly like this, the bartender does not associate 
a command number with the menu items. In this case, the bartender’s 
FindCmdNumber returns the negative of the menu ID in the high word and 
the item ID in the low word. 


The values that FindCmd 
returns in these cases are 
the negative of what 
MenuSelect would 
have returned 


For example, if you choose the ninth font in the Font menu, 
FindCmdNumber returns -655369 (0xFFF5FFF7). Since the number is 
negative, you know that there is no command number associated with the 
item. To get the menu ID and the menu item, negate the value and split it 
into two words. In this example, the return value becomes 655369 
(0x0 0 0A0 0 0 9), which means that the menu ID is 10 and the menu item is 9. 


-a 


menuID 


menultem 


Figure 13-2 How FindCmdNumber builds command numbers. 


Note 

There are functions to extract the high word and low word 
of a long integer. In THINK Pascal, the functions are 
Hi Word and LoWord. In THINK C, the functions are 
Hi Short and LoShort (defined in Global. h). 


You can add menu items to existing menus if you like. You might want to 
add the Font menu to a general text-handling menu, or you might want to 
have a menu with the names of all the documents your application has 
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opened. The important thing to remember is to add all these menu items at 
the end of the existing menu. Otherwise, the bartender will get confused. 

Creating hierarchical menus 

For a detailed description of Most of the time you’ll be able to set up your hierarchical menus in your re- 
hierarchical menus, see In- source file. The key thing to remember is that the item that the hierarchical 
side Macintosh V, Chapter menu is attached to uses the command key equivalent and the item mark 
13, "The Menu Manager. " differently. The command key value must be OxlB (Control- [), and the val¬ 
ue of the item mark is the resource ID of the hierarchical menu. 

Sometimes, you can’t specif/ a hierarchical menu in a resource. In these cas¬ 
es, use the InsertHierMenu method. This method adds the hierarchical 
menu to an existing menu in the menu bar and to the bartender’s table. Gen¬ 
erally, you’ll specify hierarchical menus in your resource file. Use this meth¬ 
od to insert hierarchical menus from your program. 


Note 

For hierarchical menus to work correctly, you must set 
them up either in the resource file or with a call to 
InsertHierMenu. If you use only the Macintosh Toolbox 
routines, the bartender’s item checking methods will not 
work. 


This example shows how to write a method in THINK Pascal to insert a hier¬ 
archical Font menu as the third item in a Text menu from your program: 

procedure CYourApp.SetUpMenus; 
var 

macMenu: MenuHandle; 

MENUtext, itemNo: integer; 
begin 

inherited SetUpMenus; 

gBartender.InsertHierMenu(MENUfont, cmdNull, 
MENUtext, 2); 

AddResMenu(GetMHandle(MENUfont), 'FONT'); 

gBartender.SetDimOption(MENUfont, dimNONE); 
gBartender.SetUnchecking(MENUfont, true); 
end; 
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The dimming, undimming, 
and unchecking take very 
little time. You won't notice 
a delay between the time 
you dick on the menu bar 
and when the menu is dis¬ 
played. 


_ Using CBartender ^ 

And this example shows how to write a method in THINK C to do the same 
thing: 

void CYourApp::SetUpMenus() 

{ 

MenuHandle macMenu; 

short MENUtext , itemNO; 

inherited::SetUpMenus(); 

gBartender->InsertHierMenu(MENUfont, cmdNull, 
MENUtext r 2); 

AddResMenu(GetMHandle(MENUfont), 'FONT'); 
SetDimOption(MENUfont, dimNONE); 

SetUnchecking(MENUfont, TRUE); 

} 

Dimming and checking menu items 

The bartender includes methods to let you enable and disable and check 
and uncheck menu items. When you click in the menu bar, the bartender 
sends an UpdateMenus message to all of the bureaucrats in the Chain of 
Command. In the general case, all the items in the menu start out dimmed 
and unchecked. Then each bureaucrat enables the menu items that pertain 
to it. Once the appropriate items have been enabled and checked, the Tool¬ 
box routine MenuSelect displays all the menus. 

Suppose you click in the menu bar of a text processing application. When 
you click on the menu bar, but before the Toolbox displays the menu, the 
bartender disables all the menu items. Then, the application enables all the 
application related menu items: New, Open..., Quit, for example. The doc¬ 
ument enables all the document related items: Save, Save As..., Revert (if 
the document’s been changed), and so on. A pane might check the current 
font and size in the Font menu. Finally the menu appears on the screen with 
the correct items checked and enabled. 

The UpdateMenus method of your application, document, and pane need 
to enable each item. To make sure that item enabling happens from the gen¬ 
eral (application) to the specific (pane), be sure to call inherited 
UpdateMenus first in your own UpdateMenus method. 

You can use the bureaucrat methods SetDimOpt ion and 
SetUnchecking in your application SetUpMenus method to modify this 
behavior. SetDimOpt ion lets you specify whether the bartender should 
dim all, some, or none of the items when you click on the menu bar. For 
Font menus, for instance, it doesn’t make sense to dim all the font names 
only to re-enable them again. 
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Variables 

The global variable gBartender points to the single instance of the bar¬ 
tender. Whenever you want to manipulate menus, you’ll send messages to 
this object. The bartender uses its instance variables to maintain the map¬ 
ping between command numbers and menu items. You should not need to 
access or alter the instance variables. 


Global variable 

Variable 

Type 

Description 

gBartender 

CBartender 

The global bartend¬ 
er. 

Instance variables 

Variable 

Type 

Description 

numMenus 

integer 

The number of 
menus available. 

theMenus 

MenuEntryH 

A table with an entry 
for each available 

menu. 

choreAssigned 

Boolean 

TRUE if there’s a 
pending chore to re¬ 
draw the menu bar 

forceMBarUpdate 

Boolean 

TRUE if 

UpdateMenuBar 
always draws the 
menu bar. 


Methods 

To use these methods to manipulate menus and menu items, send messages 
to the bartender object stored in the global gBartender. 

For example, to disable the Open... command you would write, in THINK 
Pascal: 

gBartender.DisableCmd(cmdOpen); 

And in THINK C you would write: 

gBartender->DisableCmd(cmdOpen); 

To change the name of the Copy command to Copy Picture, you might 
write, in THINK Pascal: 

gBartender.SetCmdText(cmdCopy, 'Copy Picture'); 
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IBartender 


AddMenu 


RemoveMenu 


InsertlnBar 


DeleteFromBar 


And in THINK C you might write: 

gBartender->SetCmdText(cmdCopy, 

M \pCopy Picture"); 

In the rare case where you need the actual menu handle or other informa¬ 
tion about the menu, use the FindMacMenu or FindMenuItem methods. 

Construction methods 

procedure IBartender (MBARid: integer); 
void IBartender (short MBARid); 

Initialize a Bartender object. The application method SetUpMenus sends 
this message to initialize the bartender and stores the bartender in the global 
variable gBartender. MBARid is the ID of the MBAR resource that the bar¬ 
tender uses to build its menu tables. The default SetUpMenus method uses 
1 as its MBARid. 

Insertion and deletion methods 

procedure AddMenu (MENUid: integer; 

install: Boolean; beforelD: integer); 

void AddMenu (short MENUid, Boolean install, 
short beforelD); 

This method adds a menu to the bartender’s list. MENUid is the resource ID 
of the menu. If install is TRUE, install it into the menu bar as well as into 
the bartender’s list. BeforelD specifies before which menu this menu is in¬ 
stalled. If beforelD is 0, the menu is added to the end of the menu bar. A 
beforelD of -1 is a hierarchical or pop-up menu. 

procedure RemoveMenu (MENUid: integer); 
void RemoveMenu (short MENUid); 

Remove the specified menu from the menu bar and from the bartender’s list. 
MENUid is the resource ID of the menu. 

procedure InsertlnBar (MENUid, beforelD: integer); 
void InsertlnBar (short MENUid, short beforelD); 

Insert a menu in the menu bar and in the bartender’s list. This message is the 
same as AddMenu(MENUid, TRUE, beforelD). 

procedure DeleteFromBar (MENUid: integer); 
void DeleteFromBar (short MENUid); 

Remove the specified menu from the menu bar, but leave it in the list. After 
deleting the menu, this method creates a chore of class CMBarChore and 
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InsertHierMenu 


EnableCmd 


DisableCmd 


EnableMenu 


DisableMenu 


EnableMenuBar 


DisableMenuBar 


sends it to gApplication as an urgent chore. The chore will redraw the 
menu bar the next time through the event loop. 

procedure InsertHierMenu (hMENUid: integer; 

cmdNo: longint; inMENUid, afteritem: integer); 

void InsertHierMenu (short hMENUid, long cmdNo, 
short inMENUid, short afteritem); 

Insert a hierarchical menu in another menu. HMENUid is the menu ID of the 
hierarchical menu. If you want to be able to dim a hierarchical menu, pro¬ 
vide a command number in cmdNo; if you’re not going to dim the hierarchi¬ 
cal menu, pass in cmdNull for cmdNo. InMENUid is the menu ID of the 
menu that will contain the hierarchical menu. Afteritem is the item num¬ 
ber after which the hierarchical menu should be inserted. The title of the 
menu is used as the item name for the hierarchical menu. 

Item manipulation methods 

procedure EnableCmd (cmdNo: longint); 
void EnableCmd (long cmdNo); 

Enable the menu item associated with cmdNo. 

procedure DisableCmd (cmdNo: longint); 
void DisableCmd (long cmdNo); 

Disable the menu item associated with cmdNo. 

procedure EnableMenu (MENUid: integer); 
void EnableMenu (short MENUid); 

Enable the menu with resource ID MENUid. 

procedure DisableMenu (MENUid: integer); 
void DisableMenu (short MENUid); 

Disable the menu with resource ID MENUid. 

procedure EnableMenuBar; 
void EnableMenuBar (void); 

Enable all the menus currently in the menu bar. 

procedure DisableMenuBar; 
void DisableMenuBar (void); 

Disable all the menus currently in the menu bar. 
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SetCmdText 


GetCmdText 


CheckMarkCmd 


InsertMenuCmd 


RemoveMenuCmd 


FindCmdNumber 


Methods 
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procedure SetCmdText (cmdNo: longint; 
theText: Str255); 

void SetCmdText (long cmdNo, Str255 theText); 

Change the text of the menu item associated with cmdNo to theText. 

procedure GetCmdText (cmdNo: longint; 
var theText: Str255); 

void GetCmdText (long cmdNo, Str255 theText); 

Get the text of the menu item associated with cmdNo. If cmdNo is not associ¬ 
ated with a menu item, the contents of theText are unchanged. 

procedure CheckMarkCmd (cmdNo: longint; 
checked: Boolean); 

void CheckMarkCmd (long cmdNo, Boolean checked); 

Place (or remove) a check mark next to the menu item associated with 
cmdNo. 

Item Insertion and deletion 

procedure InsertMenuCmd (cmdNo: longint; 

theText: Str255; MENUid, afteritem: integer); 

void InsertMenuCmd (long cmdNo, Str255 theText, 
short MENUid, short afteritem) ; 

Insert a new item in a menu. CmdNo is the command number of the new 
item. TheText is the text of the new item. MENUid is the menu ID you’re 
inserting the new item into. Afteritem specifies after which item to insert 
the new item. 

procedure RemoveMenuCmd (cmdNo: longint); 
void RemoveMenuCmd (long cmdNo); 

Remove the menu item associated with the command cmdNo from its menu. 

Look-up methods 

These methods let you know which command number is associated with 
which menu item and which menu contains the menu item associated with a 
particular command number. 

function FindCmdNumber (MENUid, itemNo: integer): 
longint; 

long FindCmdNumber (short MENUid, short itemNo); 

Return the command number associated with the menu MENUid and 
itemNo. If the item has no command associated with it, this method returns 
-MENUid in the high word and itemNo in the low word. 
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FindMenultem 


FindltemText 


FindMacMenu 


FindMenuIndex 


SetDImOption 


This is the message that the desktop and switchboard send to the bartender 
to convert a menu selection or a menu key into a command number. Some 
menu items, like font menus, don’t have commands associated with them. 
For these menus, FindCmdNumber returns the menu id and item number. 

procedure FindMenultem (cmdNo: longint; 

var MENUid: integer; var macMenu: MenuHandle; 
var itemNo: integer); 

void FindMenultem (long cmdNo, short *MENUid, 
MenuHandle *macMenu, short *itemNo); 

Given a command number, return the menu ID, the handle to the menu, and 
the item number. If the command number isn’t associated with a menu item, 
all three items are set to zero. 

function FindltemText; (MENUid: integer; 
itemStr: Str255): integer; 

short FindltemText (short MENUid, Str255 itemStr); 

Return the item number in MENUid with the specified text. Return 0 if the 
menu doesn’t have an item called itemStr. This method is useful for keep¬ 
ing track of items that don’t have command numbers associated with them. 

function FindMacMenu (MENUid: integer): MenuHandle; 
MenuHandle FindMacMenu (short MENUid); 

Return a handle to the Macintosh menu with ID MENUid. If the menu is not 
in the bartender’s table, return NIL. 

function FindMenuIndex (MENUid: integer): integer; 
short FindMenuIndex (short MENUid); 

Return the index of the menu MENUid in the bartender’s table. This is an in¬ 
ternal method. You should not use this method. 

Appearance methods 

procedure SetDimOption (MENUid: integer; 
aDimming: DimOption); 

void SetDimOption (short MENUid, DimOption aDimming); 
Set the dim option for the specified menu. By default, all the items in the 
menu will be dimmed when you click in the menu bar. The UpdateMenus 
method of each of your bureaucrats needs to enable the appropriate items. 
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SetUnchecking 


UpdateAHMenus 


UpdateMenuBar 


Dim Option Meaning 

dimNONE Never dim any of the menu items. 

dimSOME Dim only the menu items that have com¬ 

mand numbers associated with them. 
dimALL Dim all of the menu items. Each bureau¬ 

crat’s UpdateMenus method must enable 
the items for the commands it handles. 

This is the default. 

procedure SetUnchecking (MENUid: integer, 
anUnchecking: Boolean); 

void SetUnchecking (short MENUid, 

Boolean anUnchecking); 

Set the checking option for the specified menu. By default, none of the items 
are unchecked when you click in the menu bar. If you set this option to 
TRUE, all the items will be unchecked, and your UpdateMenus methods 
must check the appropriate menu items. 

If anUnchecking is... Do this... 

TRUE Uncheck all the menu items at menu se¬ 

lection. Your UpdateMenus method 
should check the appropriate items. Set 
this option for menus like Font menus or 
Style menus. 

FALSE Don’t uncheck any menu items at menu 

selection. This is the default since most 
menu items never need to be checked. 

procedure UpdateAHMenus; 
void UpdateAHMenus (void) ; 

The bartender gets this message before menu selection. First it disables and 
unchecks all the items in the menus according to the dimming and uncheck¬ 
ing options. Then it sends an UpdateMenus message to the gopher to en¬ 
able the appropriate menu items. You should not use or override this 
method. 

procedure UpdateMenuBar; 
void UpdateMenuBar (void); 

If the menu bar needs to be redrawn, call DrawMenuBar. The menu bar 
needs to be redrawn if the f orceMBarUpdate flag is TRUE, or if the en¬ 
abled state of any menu in the menu bar doesn’t match the last recorded 
state. 
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Command Extraction methods 

These three methods are internal methods that the bartender uses to find 
commands associated with menu items and to build its internal data struc¬ 
tures. You should not use these methods. These are the THINK Pascal meth¬ 
ods: 

procedure ExtractCommands: (var theEntry: MenuEntry); 

procedure ParseltemString (var itemStr: Str255; 
var cmdNo: longint); 

procedure ExtractHierMenus (macMenu: MenuHandle; 
index: integer); 

And these are the THINK C methods: 

void ExtractCommands (MenuEntryP theEntry); 

void ParseltemString (Str255 itemStr, long *cmdNo); 

void ExtractHierMenus (MenuHandle macMenu, 
short index); 
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Introduction 

CBitMap is a class for working with Macintosh bit maps. You should be fa¬ 
miliar with QuickDraw bit maps to get the most out of this class. 

Heritage 

Superclass CObject 

Subclasses None 

Using CBitMap 

CBitMap gives you methods to draw into a bit map, to stamp a bit map on 
the current drawing port, and to get a bit map from the current drawing port. 
You may notice that this class doesn’t provide a drawing method. That’s be- 
casue this class is only for manipulating bit maps. The class CBitMapPane 
gives you a pane for drawing bit maps. 

To learn more about trans¬ 
fer modes see Inside Mac¬ 
intosh I, Chapter 6, 

"QuickDraw." 


To draw into an off-screen bit map, bracket your drawing routines with calls 
to BeginDrawing and EndDrawing. When you create the bit map object, 
you have the choice of creating a drawing port for it or not. If you choose to 
create a port, your bit map will have a complete QuickDraw environment 
when you draw to it. If you don’t, the drawing routines use the drawing en¬ 
vironment of the current port. 

In general, you should create a port for a bit map whenever you intend to 
draw to a bit map. If you use a bit map only to hold an image that you cop¬ 
ied from or want to copy to the current port, you don’t need to create a port. 


Use the Copy From method to copy bits from your bit map object to the bit 
map of the current QuickDraw port. To copy bits from the current port to 
your bit map object, use the Copy To method. The transfer mode determines 
how the bit mapped is copied. Use the GetXf erMode method to examine 
the current transfer mode and the SetXf erMode method to set the transfer 
mode. The default transfer mode is srcCopy 
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For example, this Pascal procedure draws a diagonal line in an off-screen bit 
map.: 

procedure DrawIntoOffScreenBitMap; 
var 

myBitMap: CBitMap; 
begin 

new (myBitMap) ; 

myBitMap.JBitMap(300, 300, TRUE); 
myBitMap.BeginDrawing; 

MoveToCLO, 10); 

LineTo(200, 200); 
myBitMap.EndDrawing; 
end; 

This is what the same routine looks like in C: 

void DrawIntoOffScreenBitMap(void) 

{ 

CBitMap *myBitMap; 

myBitMap = new(CBitMap); 
myBitMap->IBitMap(300, 300, TRUE); 
myBitMap->BeginDrawing; 

MoveTo(10, 10); 

LineTo (200, 200); 
myBitMap->EndDrawing; 

}; 

Once you Finish drawing into your bit map, you can use the Copy From 
method to stamp it into the curent port To save the bit map as a paint 
(PNTG) File, you can use the CPNTGFile class. 


Variables 



Variable 

Type 

Desktop 

macPort 

GrafPtr 

Graf port for the bit map if 
requested. 

savePort 

GrafPtr 

Used internally to save the 
original drawing port if 
necessary. 

macBitMap 

BitMap 

The bit map. 

saveBitMap 

BitMap 

Used internally to save the 
original drawing port’s bit 
map if necessary. 

xferMode 

Integer 

Bitmap transfer mode. Ini¬ 
tially srcCopy. 
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IBitMap 


Free/Dispose 


GetBounds 


SetBoundsOrigin 


SetXferMode 


GetXferMode 


PixellsBIack 
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Methods 

Construction and destruction methods 

procedure IBitMap (width, height: Integer; 
makePort: Boolean); 

void IBitMap (short width, short height. 

Boolean makePort); 

Initialize the bit map. This method allocates memory for the bit map. The or¬ 
igin is set to (0, 0), and the transfer mode is set to srcCopy. If makePort is 
TRUE, IBitMap creates a QuickDraw grafport whose port bits point to the 
bit map. In general, you should pass TRUE for makePort if you intend to 
draw to the bit map and FALSE if you use the bit map only to hold an image. 

procedure Free; 
void Dispose (void); 

Dispose of the bit map. This method releases memory allocated to the bit 
map and closes the macPort if it was opened. 

Accessing methods 

procedure GetBounds (var theBounds: LongRect); 
void GetBounds (theBounds *LongRect); 

Get the bounding rectangle of the bit map. This rectangle describes the size 
and coordinate system of the bit map. 


procedure SetBoundsOrigin (hOrigin, vOrigin: integer); 
void SetBoundsOrigin (short hOrigin, short vOrigin); 

Set the coordinates of the top left corner of the bit map. This method chang¬ 
es the coordinate system of the bit map. 

procedure SetXferMode (aXferMode: Integer); 
void SetXferMode (short aXferMode); 

Set the transfer mode of the bitmap. 

function GetXferMode: Integer; 
short GetXferMode (void); 

Return the transfer mode of the bit map. 

function PixellsBIack (pixelPos: LongPt): Boolean; 
Boolean PixellsBIack (LongPt pixelPos); 

Return TRUE if the pixel specified by pixelPos is black. Return FALSE if it 
isn’t or if the specified position is not in the bit map. 
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CopyTo 


CopyFrom 


BeginDrawing 


End Drawing 


Image copying methods 

procedure CopyTo (fromRect, toRect: LongRect; 
maskRgn: RgnHandle); 

void CopyTo (LongRect *fromRect, LongRect *toRect, 
RgnHandle maskRgn); 

Copy bits to this bit map from the current port (thePort). FromRect is a 
rectangle in thePort’s bit map, and toRect is a rectangle in this bit map. 
If maskRgn is NIL, this method does no clipping. Otherwise, the transfer is 
clipped to maskRgn, a region in this bit map’s coordinates. The transfer 
mode is stored in the xf erMode instance variable 

procedure CopyFrom (LongRect, LongRect: Rect; 
maskRgn: RgnHandle); 

void CopyFrom (LongRect *fromRect, LongRect *toRect, 
RgnHandle maskRgn); 

Copy bits from this bit map to the current port (thePort). FromRect is a 
rectangle in this bit map, and toRect is a rectangle in thePort’s bit map. 
If maskRgn is NIL, this method does no clipping. Otherwise, the transfer is 
clipped to maskRgn, a region in thePort’s coordinates. The transfer mode 
is stored in the xf erMode instance variable 

Drawing preparation methods 

procedure BeginDrawing; 
void BeginDrawing (void); 

Prepare for drawing to this bit map. It the bit map doesn’t have its own port, 
set the port bits of the current port to this bit map. If the bit map has its own 
port, this method saves the current port and sets the bit map’s port as the 
current port. 

procedure EndDrawing; 
void EndDrawing (void); 

Reset the port to the state before drawing. If the bit map doesn’t have its 
own port, restore thePort’s port bits from saveBitMap, otherwise reset 
the port to savePort. 
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For static imagesa picture 
pane is easier to use. See 
the CPicture class on page 
183 . 


CBitMapPane « 

IS 


Introduction 

CBitMapPane is a subclass of CPanorama for drawing bit maps in a pane. 

Heritage 

Superclass CPanorama 

Subclasses None 

Using CBitMapPane 

CBitMapPane is a pane with an associated bit map. The drawing method of a 
bit map pane copies from the bit map to the pane’s drawing port. That 
means that your program should draw into the bit map pane’s bit map be¬ 
fore the drawing method gets called. The Art Class demonstration program, 
which uses a subclass of CBitMapPane, draws directly on the screen and on 
the associated bit map in a mouse task. When the Macintosh generates an 
update event, the pane’s drawing method copies the associated bit map 
right on the screen, giving a very smooth update. 

Though you can use CBitMapPane directly, you will probably want to use a 
subclass of it so you can add instance variables and methods tailored for 
your application. Your program can use whatever technique is appropriate 
to fill the bit map with an image. If the image doesn’t change, your program 
can just read the bit map from a file and rely on the update event to stamp 
the image on the screen. If it’s an interactive image, you might use a mouse 
task like Art Class does. If it’s a complex image and you want to give the illu¬ 
sion of a quick update, you do the drawing to the bit map in your subclass’s 
Draw method with CBitMap’s BeginDrawing and EndDrawing methods, 
then call the inherited Draw method do stamp the image on the screen. 
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Variables 

Variable Type Desktop 

itsBitMap CBitMap The bitmap to stamp on 

the pane. 

Methods 

Construction and destruction methods 

IBitMapPane procedure IBitMapPane (anEnclosure: CView; 

aSupervisor: CBureaucrat; 
aWidth, aHeight: integer; 
aHEncl, aVEncl: integer; 
aHSizing, aVSizing: SizingOption; 
aBounds: LongRect; 

aBitMap: CBitMap; makePort: Boolean); 

void IBitMapPane (CView *anEnclosure, 

CBureaucrat *aSupervisor, 
short aWidth, short aHeight, 
short aHEncl, short aVEncl, 

SizingOption aHSizing, SizingOption aVSizing, 
LongRect *aBounds, 

CBitMap *aBitMap, Boolean makePort); 

Initialize a panorama. The first eight arguments to this routine are identical 
to the ones for I Pane. 

The aBounds rectangle is a long rectangle that defines the bounds of the 
panorama. The bounds define the height and width of aBitMap as well as 
its coordinate system. 

If aBitMap is NIL, IBitMapPane creates a new bit map object for the 
pane, otherwise it uses aBitMap as the pane’s bit map. When you use an 
existing bit map, be sure to get pass the correct bounds to IBitMapPane. 
Send the bit map a GetBounds message to get its bounds, and pass the re¬ 
sults to IBitMapPane. 

IBitMapPane passes the makePort parameter to CBitMap’s IBitMap 
method. If aBitMap is not NIL, this parameter is ignored. The makePort 
parameter specifies whether the bit map should have a drawing environ¬ 
ment. In general, you should always pass TRUE for this parameter. 


Note 

The descriptions of the other arguments are in CPane on 
page 321. 
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SetBItMap 


GetBitMap 
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♦ 

procedure Free; 
void Dispose (void); 

Dispose of the bit map. This method releases memory allocated to the bit 
map and closes the mac Port if it was opened. 

Accessing methods 

procedure SetBitMap (aBitMap: CBitMap); 
void SetBitMap (CBitMap *aBitMap); 

Get the bounding rectangle of the bit map. This rectangle describes the size 
and coordinate system of the bit map. 

function GetBitMap: CBitMap; 

CBitMap *GetBitMap (void); 

Get the bit map associated with this pane. 

Drawing method 

procedure Draw (var area: Rect); 
void Draw (Rect *area); 

Draw the bit map. Copy the bits in the bit map to the bit map of the current 
port. 
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CBureaucrat * 

16 


Introduction 

CBureaucrat is an abstract class that implements a link in the chain of com¬ 
mand. Any object in the THINK Class Library that responds to a menu com¬ 
mand or a mouse click is a bureaucrat. 

A bureaucrat can either respond to a command, or it can pass the command 
to its supervisor. All of the default methods for bureaucrats pass the message 
on to the supervisor, so if a particular subclass cannot handle the message, 
calling the inherited method will cause the message to be passed on up the 
chain of command. 

Heritage 

Superclass CCollaborator 

Subclasses CDirectorOwner 

CView 


Using CBureaucrat 

You generally won’t need to create a subclass of CBureaucrat because most 
of the objects you’ll use are already descendants of this class. However, you 
may find that you need to create a class that’s a link in the chain of command 
that’s not one of the common objects. 

The global variable gGopher points to the current bureaucrat which is the 
first object in the chain of command. Whenever the switchboard responds to 
an event, it sends an appropriate message to the gopher. For instance, in re¬ 
sponse to a key-down event, the switchboard sends a DoKeyDown message 
to the gopher. 

If the object gGopher refers to cannot handle the command, it passes the 
message up the chain of command until the message reaches an object that 
handles the command or until it reaches the end of the chain of command— 
the application. 
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♦ 


When there are no documents open, gGopher points to the application. 
When you open a document, gGopher points to the document. Your docu¬ 
ment subclass should use the BecomeGopher method to change gGopher 
to point to the main pane. 

Be sure to use the BecomeGopher method to change the gopher instead of 
setting the gGopher variable yourself. BecomeGopher uses CCollabora- 
tor’s provider/dependent mechanism to let dependent objects know that the 
gopher has changed. 

Variables 

Global variable 

Variable Type Description 

gGopher CBureaucrat The current bureaucrat. 

Instance variable 

A bureaucrat has only one instance variable. 

Variable Type Description 

itsSupervisor CBureaucrat The supervisor. 

Methods 

Construction and destruction methods 

IBureaucrat procedure IBureaucrat (aSupervisor: CBureaucrat); 

void IBureaucrat (CBureaucrat *aSupervisor); 

Initialize the bureaucrat. This method sets aSupervisor to be 
itsSupervisor 

Free/Dlspose procedure Free; 

void Dispose (void); 

If the bureaucrat is the gopher, send a BecomeGopher (TRUE) message to 
the supervisor before disposing of the object. 

Accessing method 

GetSupervIsor function GetSupervisor: CBureaucrat; 

CBureaucrat *GetSupervisor (void); 

Return the bureaucrat’s supervisor 

Command methods 

These are the messages that every bureaucrat accepts. Unless a bureaucrat 
(or one of its ancestors) overrides one of these methods, it just passes the 
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Notify 


DoKeyDown 


DoAutoKey 


DoKeyUp 


DoCommand 


Methods 

- - * 

message to its supervisor. If you follow the chain of supervisors—the chain 
of command—all the way to the end, you’ll end up at your application class. 

procedure Notify (theTask: CTask); 
void Notify (CTask *theTask); 

A task has been completed. This method passes the Notify message to the 
bureaucrat’s supervisor. 

procedure DoKeyDown (theChar: char; keyCode: Byte; 
macEvent: EventRecord); 

void DoKeyDown (char theChar, Byte keyCode, 

EventRecord *macEvent); 

Handle a key-down event. This method passes the DoKeyDown message to 
the bureaucrat’s supervisor. 

procedure DoAutoKey (theChar: char; keyCode: Byte; 
macEvent: EventRecord); 

void DoAutoKey (char theChar, Byte keyCode, 

EventRecord *macEvent); 

Handle an auto-key event. This method passes the DoAutoKey message to 
the bureaucrat’s supervisor. 

procedure DoKeyUp (theChar: char; keyCode: Byte; 
macEvent: EventRecordPtr); 

void DoKeyUp (char theChar, Byte keyCode, 

EventRecord *macEvent); 

Handle a key-up event. This method passes the DoKeyUp message to the 
bureaucrat’s supervisor. 


Note 

By default, the Toolbox Event Manager masks out key-up 
events. 


procedure DoCommand (theCommand: longint); 
void DoCommand (long theCommand); 

Handle a command. This method passes the DoCommand message to the 
bureaucrat’s supervisor. 
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♦- 

DoAppleEvent 


Dawdle 


UpdateMenus 


procedure DoAppleEvent (anAppleEvent: CAppleEvent); 
void DoAppleEvent (CAppleEvent *anAppleEvent); 

Handle an AppleEvent. This method passes the AppleEvent to the bureau¬ 
crat’s supervisor. 

procedure Dawdle (var maxSleep: longint); 
void Dawdle (long *maxSleep); 

Perform periodic actions at idle time. The default method does nothing. 
CApplication’s Idle method sends a Dawdle message to all of the bureau¬ 
crats in the chain of command. 

If your bureaucrat requires periodic actions, perform them in the Dawdle 
method. Set the value of maxSleep to the largest number of ticks that your 
application can tolerate between Dawdle messages. If your application’s 
Dawdle message doesn’t have any time constraints, you can ignore 
maxSleep. 

The application class uses the value of maxSleep to let WaitNextEvent 
know that it should yield an event after at most maxSleep ticks. For in¬ 
stance, the Dawdle method for CEditText calls TEIdle to blink the inser¬ 
tion point and sets maxSleep to GetCaretTime which is the rate at which 
the insertion point blinks. 

A blinking insertion point is a good example. A clock display is another 
good example. You would update the display from your document’s 
Dawdle method. If your clock displays seconds, set maxSleep to 60 since 
you need to update the display at least every 60 ticks. 

On a null event, CApplication’s Idle method sends a Dawdle message to 
every bureaucrat in the chain of command. Idle sets the global variable 
gSleepTime to the smallest sleep time that all bureaucrats requested. The 
switchboard uses this global variable in its call to WaitNextEvent. 

procedure UpdateMenus; 
void UpdateMenus (void) ; 

Update the menus that have to do with this bureaucrat. Your bureaucrat 
(usually a document or a pane) should override this method to enable the 
menu items that pertain to it. The important thing to remember when you 
write an UpdateMenus method is to call inherited UpdateMenus 
before you enable your own menus. In this way, your supervisor’s menus 
will be updated first. See CBartender, especially section “Dimming and 
checking menu items” on page 171, for a discussion of menu updating. 
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function BecomeGopher (fBecoming: Boolean): Boolean; 
Boolean BecomeGopher (Boolean fBecoming); 

If fBecoming is TRUE, make this bureaucrat the gopher and call 
BroadcastChange with bureaucrat I sGopher as the reason. If 
fBecoming is FALSE, call BroadcastChange with 
bureaucrat I sNotGopher as the reason. 

If the current gopher refuses to relinquish control, this method returns 
FALSE and does not call BroadcastChange at all. 

Change notification methods 

These methods override methods in CCollaborator. To learn how to use 
them, see CCollaborator on page 223. 

procedure BroadcastChange (reason: longint; 
info: Ptr); 

void BroadcastChange (long reason, void* info); 

In addition to notifying this bureaucrat’s dependents of a change, notify its 
supervisor as well. Reason is an integer that describes the type of change. 
You must define reasons for your subclass. Inf o is a pointer to any addi¬ 
tional information needed to respond to the change. If you want objects that 
aren’t in a collaborator’s list of dependents to know about a change, override 
this method 

procedure ProviderChanged (aProvider: CCollaborator; 
reason: longint; info: Ptr); 

void ProviderChanged (CCollaborator *aProvider, 
long reason, void* info); 

One of this bureaucrat’s providers has just changed. This method passes the 
change notification to the bureaucrat’s supervisor. If you want your subclass 
to respond to change notifications, you should override this method. 
aProvider is the provider that changed. Reason is an integer that de¬ 
scribes the type of change. You must define reasons for your subclass. Info 
is a pointer to any additional information that your subclass might need. 
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17 


Introduction 

CButton implements a standard Macintosh push button. You can use a but¬ 
ton in any pane or window. 

Heritage 

Superclass CControl 

Subclasses CCheckBox 

CRadioControl 


Using CButton 

CButton implements a standard Macintosh push button. You should not 
override this class unless you want to implement a push button that works 
differently from the default button. (The other kinds of Macintosh buttons, 
check boxes and radio buttons, are subclasses of this class.) 

The CButton class handles all the mouse tracking for you. When you click 
and release the mouse button within a button, the button sends a 
DoCommand message to its supervisor. To specify which command number 
the button will send in the DoCommand message, send it a SetClickCmd 
message. 

This is what happens when you click in a button. The DoClick method that 
CButton inherits from CControl calls the Macintosh Toolbox routine 
TrackControl to highlight the button and track mouse movement. When 
you release the mouse within a button, the DoClick method sends the con¬ 
trol a DoGoodClick message. The DoGoodClick method sends the 
DoCommand message to the button’s supervisor. 
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INewButton 


Variables 

Variable Type Description 

clickCmd longint Command number to send 

after a dick. The default is 
cmdNull. 

Methods 

Although CButton implements only these methods, you can use the meth¬ 
ods it inherits from CControl and CView to manipulate a button’s title and lo¬ 
cation. 

procedure IButton (CNTLid: integer; 

anEnclosure: CView; aSupervisor: CBureaucrat); 

void IButton (short CNTLid, CView *anEnclosure, 
CBureaucrat *aSupervisor); 

Initialize a button from a CNTL resource (a control template). CNTLid is the 
resource ID of the CNTL resource. AnEnclosure is the pane or window 
that the control belongs to. ASupervisor is the control’s supervisor, typi¬ 
cally a document. 

IButton places the control at the location specified in the CNTL resource. 
If you want to position the button from your program, send it a Place mes¬ 
sage. (Controls inherit the Place method from CPane.) 

procedure INewButton (aWidth, aHeight: integer; 
aHEncl, aVEncl: integer; title: StringPtr; 
fVisible: Boolean; procID: integer; 
anEnclosure: CView; aSupervisor: CBureaucrat); 

void INewButton (short aWidth, short aHeight, 
short aHEncl, short aVEncl, StringPtr title. 

Boolean fVisible, short procID, 

CView *anEnclosure, CBureaucrat *aSupervisor); 
Initialize a button from the parameters in the argument list. Title is the 
name of the button. FVisible specifies whether the button is drawn initial¬ 
ly. ProcID specifies what type of button to create. Its possible values are 
defined in Cont rols. h and include pushButP roc, checkBoxP roc, and 
radioButProc. 


Note 

The descriptions of the other arguments are in CPane on 
page 321. 
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CetClickCmd 


SetClickCmd 


SetDefault 


SimulateClick 


DoCoodClick 


function GetClickCmd: longint; 
long GetClickCmd (void); 

Return the command which is sent to a button’s supervisor when the user 
clicks in a button. 

procedure SetClickCmd (aClickCmd: longint); 
void SetClickCmd (long aClickCmd); 

Set the command number to be sent when the user clicks in a button. 

procedure SetDefault (fDefault: Boolean); 
void SetDefault (Boolean fDefault); 

Specify whether the button is the default button. The default button has a 
three-pixel thick rounded rectangle as its border. 

procedure SimulateClick; 
void SimulateClick (void) ; 

Simulate a click in this button. Use this method when you want to provide 
visual feedback for a Command key shortcut. This method highlights the 
button momentarily, then sends a DoGoodClick message to the button. 

procedure DoGoodClick (whichPart: integer); 
void DoGoodClick (short whichPart); 

When you press and release the mouse within the button, this method sends 
a DoCommand message to its supervisor. This is an internal method. You 
should not use or override this method. 
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18 


Y 1 


Introduction 

CCharGrid is a subclass of CGridSelector that displays characters in a table 
and lets you choose one. CCharGrid is useful for implementing tool palettes 
like MacPaint and HyperCard. 

Heritage 

Superclass CGridSelector 

Subclasses None 


Using CCharGrid 

The CCharGrid class lets you create panes that display characters in a table. 
The most common use for this kind of table is a tool palette. You can use a 
CCharGrid as a tool palette that’s part of a window or as a custom tear-off 
menu. The Art Class demonstation program uses CCharGrid to display its 
Tool tear-off menu. 



Figure 18-1 Art Class uses CCharGrid as a palette and as a menu 


To use a CCharGrid, you need to create a special font that contains your 
tools. You can use ResEdit to create the font, or you can use a commercial a 
bit-map font editor. Apple recommends that the family ID for these kinds of 
fonts be in the range 32256 to 32767. Check with the Font Manager chapters 
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in Inside Macintosh /and Inside Macintosh IV for detailed information about 
working with fonts.. 

Unlike other subclasses of CPane that optionally let you initialize an object 
from a resource, you must use a resource to initialize a CCharGrid. The first 
argument to the initialization method, I Char Grid, is the resource ID of a 
ChGd resource which contains the values that ICharGrid passes up to 
CGridSelector’s initialization method. The ChGd resource looks like this: 


Field 

Size 

Description 

Rows 

integer 

The number of rows in the 
grid. 

Columns 

integer 

The number of columns in 
the gird. 

Box Width 

integer 

The width in pixels of 
each box. 

Box Height 

integer 

The height in pixels of 
each box. 

Horiz. Sizing 

integer 

Horizontal sizing option. 
Usually sizFIXEDLEFT 
(0) 

Vert. Sizing 

integer 

Vertical sizing option. Usu¬ 
ally sizFIXEDTOP (2) 

Horiz. Location 

integer 

Horizontal location of grid 
in its enclosure. 

Vert. Location 

integer 

Vertical location of grid in 
its enclosure. 

Command base 

integer 

The command base for 
turning selections into 
command numbers. 

Font Size 

integer 

The size in points of the 
font. 

Font Name 

Pascal stirng 

The name of the font to 
display. 

theCharacters 

Pascal string 

Handle to a Pascal string 
of the characters to display 
in the grid. 


The first nine fields are the same as the arguments that you pass to 
If the first character of your iGridSelector. The last three are specific to character grids. The Font 
font name is "96" or ", it Size anc j Font Name fields specify the size and the name of the font to use. 
won't appear in your Font The f ont name IS a Pascal string. The last field contains the characters to dis- 
menu • play. It is also a Pascal string. 


1 98 Object-Oriented Programming 



Variables 


ICharCrid 


♦ 


The file TCL TMPLs contains ResEdit templates (' TMPL' resources) that 
help you create and edit ' ChGd' resources. This is what the ' ChGd 1 re¬ 
source in Art Class looks like when you edit it with ResEdit. 



Variables 

Variable Type Description 

theCharacters Handle Handle to a Pascal string 

of the characters to display 
in the grid. 

Methods 

Construction methods 

procedure ICharGrid. (ChGdid: integer; 

anEnclosure: CView; aSupervisor: CBureaucrat); 

void ICharGrid (short ChGdid, CView *anEnclosure, 
CBureaucrat *aSupervisor); 

Initialize the character grid. ChGdid is the resource ID of the ' ChGd 1 re¬ 
source that describes the location of the pane and the size and name of the 
font to use for the grid. See “Using CCharGrid” above for the details on 
' ChGd ' resources. ICharGrid creates a text environment object of class 
CTextEnvirons to maintain the text characteristics whenever the characters 
are drawn. The text transfer mode is initially srcOr. 
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Free/Dispose 

Drawltem 


procedure Free; 
void Dispose (void); 

Dispose of the character list and the object. 

Drawing methods 

procedure Drawltem (theltem: integer; 
theBox: Rect); 

void Drawltem (short theltem, Rect *theBox); 

Draw character numbered the I tern so it is centered within the box. Char¬ 
acters are numbered from 1. 
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CCheckBox # 

19 


Introduction 

CCheckBox implements a standard Macintosh check box. You can use a 
check box in any pane or window. 

Heritage 

Superclass CButton 

Subclasses None 

Using CCheckBox 

CCheckBox implements a standard Macintosh check box. You should not 
override this class unless you want to implement a checkbox that works dif¬ 
ferently from the default check box. 

The CCheckBox class handles all the mouse tracking for you. When you 
click and release the mouse button within a check box, it toggles the value 
of the check box and sends a DoCommand message to its supervisor. To 
specify which command number the check box will send in the 
DoCommand message, send it a SetClickCmd message. 


Note 

CCheckBox inherits the SetClickCmd method from 
CButton. 


This is what happens when you click in a check box. The DoClick method 
that CCheckBox inherits from CControl calls the Macintosh Toolbox routine 
TrackControl to highlight the check box and track mouse movement. 
When you release the mouse within a check box, the DoClick method 
sends the control a DoGoodClick message. The DoGoodClick method 
toggles the value of the control and sends the DoCommand message to the 
check box’s supervisor. 
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To find out whether the check box is checked, send it an IsChecked mes¬ 
sage. You can set the value of the check box from your program by sending 
it a SetValue message. Use the values BUTTON_ON and BUTTON_OFF to 
specify whether to check or uncheck the check box. 


Note 

Setting the value with SetValue will not send a 
DoCommand message to the check box’s supervisor. 


Variables 

This class has no instance variables. 

Methods 

Although CCheckBox implements only these methods you can use the 
methods it inherits from CControl and CView to manipulate a check box’s ti¬ 
tle and location. 

You should use the SetClickCmd method that CCheckBox inherits from 
CButton to specify the command the check box sends to its supervisor when 
you click in it. 

ICheckBox procedure ICheckBox (CNTLid: integer; 

anEnclosure: CView; aSupervisor: CBureaucrat); 

void ICheckBox (short CNTLid, CView *anEnclosure, 
CBureaucrat *aSupervisor); 

Initialize a check box from a CNTL resource (a control template). CNTLid is 
the resource ID of the CNTL resource AnEnclosure is the pane or window 
that the control belongs to. ASupervisor is the control’s supervisor, typi¬ 
cally a document. 

ICheckBox places the control at the location specified in the CNTL re¬ 
source. If you want to position the check box from your program, send it a 
Place message. (Controls inherit the Place method from CPane.) 

INewCheckBox procedure INewCheckBox (aWidth, aHeight: integer; 

aHEncl, aVEncl: integer; 

title: StringPtr; fVisible: Boolean; 

anEnclosure: CView; aSupervisor: CBureaucrat); 

void INewCheckBox (short aWidth, short aHeight, 
short aHEncl, short aVEncl, 
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StringPtr title. Boolean fVisible, 

CView *anEnclosure, CBureaucrat *aSupervisor); 

Initialize a check box from the parameters in the argument list. Title is the 
name of the check box. FVisible specifies whether the check box is 
drawn initially. 


Note 

The descriptions of the other arguments are in CPane on 
page 321. 


procedure DoGoodClick (whichPart: integer); 
void DoGoodClick (short whichPart); 

When you press and release the mouse within the check box, this method 
toggles the state of the check box and sends a DoCommand message to its 
supervisor. 

This is an internal method. You should not use or override this method. 

function IsChecked: Boolean; 

Boolean IsChecked (void); 

Returns TRUE if the check box is checked. 
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Introduction 

CChore is an abstract class for implementing periodic or uigent actions. The 
THINK Class Library executes periodic chores at idle time and urgent chores 
after processing the current event. 

Heritage 

Superclass CObject 

Subclasses CMBaiChore 

CTeaiChore 


Using CChore 

You can use this class to create chores that run at idle time or that run at the 
next possible opportunity. Your application maintains a list of chores and 
implements the methods to install and remove them. 

To implement a chore, you need to define a subclass of this class. In your 
subclass, override the Perform method. This method implements the ac¬ 
tion you want your chore to take. 

Idle chores 

To install an idle chore, send it to the application in an AssignldleChore 
message. Your application sends a Perform message to all the idle chores 
at idle time. To remove an idle chore, send the chore you want to remove to 
the application in a CancelldleChore message. This example shows 
how to install an idle chore in THINK Pascal: 

gApplication.AssignldleChore(theChore); 

And this example shows how to install an idle chore in THINK C: 

gApplication->AssignIdleChore(theChore); 
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Note 

To remove an idle chore, keep it in a variable since Can¬ 
cel I dleCho re requires a reference to a CChore object. 


Urgent chores 

An urgent chore is one that gets executed immediately after the application 
processes the current event Typically, it’s the same event that caused the ur¬ 
gent chore to be installed. Urgent chores are executed only once. They’re re¬ 
moved from the urgent chore list immediately after they’re executed. To 
install an urgent chore, send it to the application in an 
AssignUrgentChore message. 

Using chores 

Chores are attached to the application and not to any particular document 
The things that a chore does, then, should pertain to the entire application. 


Note 

If you need your chore to run at a specific interval, you can 
use the Macintosh Toolbox routine Ticks to store the last 
time the chore was performed. 


For periodic tasks that apply to a particular document or pane, use the 
Dawdle method. All bureaucrats, including documents and panes, inherit a 
Dawdle method. The application sends a Dawdle message to each bureau¬ 
crat in the chain of command. For instance, you would use a Dawdle meth¬ 
od to blink an insertion point in a pane. 

Variables 

This class has no instance variables. Your CChore subclass may define its 
own instance variables. For example, if you want your idle chore to run at 
specified intervals, you could use an instance variable to store the period. 

Methods 

CChore implements only one method, which you must override. Your 
CChore subclass may implement additional methods. 

procedure Perform (var maxSleep: longint); 
void Perform (long *maxSleep); 

This is the method that executes your chore. You must override this method 
in your CChore subclass. The default method does nothing. 
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The maxSleep parameter specifies how many ticks your chore can tolerate 
passing before it gets a Perform message. For example, if you need to do a 
chore at least once every tenth of a second, you would set maxSleep to 6. 
(Each tick is one-sixtieth of a second.) 

For a more detailed discussion of maxSleep, see the description of the 
Dawdle method in CBureaucrat on page 190. 
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Introduction 

CClipboard implements a standard Macintosh clipboard, or scrap. The de¬ 
fault clipboard handles TEXT and PICT scraps. To deal with other kinds of 
scraps or to implement a private scrap, create a subclass of this class. 

Heritage 

Superclass CDirector 

Subclasses To implement a private scrap, you should 

define a subclass. 


Using CClipboard 

This class implements a standard Macintosh clipboard. CClipboard uses the 
desk scrap to store its data and supports a window to display the contents of 
the scrap. This implementation supports only TEXT and PICT data. 

When you initialize your application, the default initialization method, 

I Application, sends a MakeClipboard message. This method creates 
an instance of CClipboard and stores it in the global variable gClipboard. 

The default application DoComraand method handles the cmdToggleClip 
command which shows and hides the Clipboard window. When you’re run¬ 
ning under MultiFinder, the Clipboard window is hidden when your applica¬ 
tion is suspended. When the application resumes, the Clipboard window 
becomes visible again. 


I 
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Note 

In the THINK Class Library, desk accessories behave as if 
they were in their own layer even if your application isn’t 
running under MultiFinder. When a desk accessory win¬ 
dow is frontmost, the Clipboard window will be hidden. 
When one of your application windows is frontmost, the 
Clipboard window will be visible again. 


Implementing a CClipboard subclass 

If you want your application to support a private scrap, or if you want to dis¬ 
play other types of data, you’ll need to implement a subclass of CClipboard. 
You’ll also need to override the MakeClipboard method in your applica¬ 
tion class. 


Note 

If you create a subclass of this class, be sure you under¬ 
stand how the Macintosh scrap mechanism works. See In¬ 
side Macintosh I, Chapter 15, “The Scrap Manager.” 


In your CClipboard subclass you’ll need to override these methods: 


Method 

PutData 

GetData 

ConvertGlobal 

ConvertPrivate 

MakeClipView 


Action 

Place data in the private scrap. 

Retrieve data from the private scrap. 

Place the contents of the desk scrap into 
the private scrap. 

Place the contents of the private scrap into 
the desk scrap. 

Create a view to display data other than 
plain text of pictures. 


Variables 

The global variable gClipboard contains a pointer to the single instance of 
the clipboard object. The value of this variable is set in the application meth¬ 
od MakeClipboard. 

Global variable 

Variable Type Description 

gClipboard CClipboard The global clipboard. 
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Instance variables 


Variable 

Type 

Description 

itsContents 

CPanorama 

Pane for displaying 

itsScrollPane 

CScrollPane 

contents 

Contents can be 

theLength 

longint 

scrolled 

Length from last Get 

theOffset 

longint 

operation 

Offset from last Get 

lastScrapCount 

integer 

operation 

Count at the last con¬ 

privateNewer 

Boolean 

version between glo¬ 
bal and private 
scraps. 

TRUE if the private 

windowVisible 

Boolean 

scrap has changed 
since the last conver¬ 
sion to the desk 
scrap. 

TRUE if the Clip¬ 

Methods 

Construction and destruction methods 

procedure IClipboard (aSupervisor: 

board window is vis¬ 
ible. 

CApplication; 


hasWindow: Boolean); 

void IClipboard (CApplication *aSupervisor, 


Boolean hasWindow); 

Initialize the clipboard. The application’s MakeClipboard method sends 
this message and stores the clipboard object in the global variable 
gClipboard. 


Note 

If you create a subclass of CClipboard, be sure to override 
the MakeClipboard method in your application subclass 
as well so it creates an object of the clipboard subclass. See 
the implementation of MakeClipboard in CApplication 
for an example. 
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Suspend and resume methods 

These methods handle scrap conversion when your application moves from 
foreground to background under MultiFinder. In most cases, you won’t need 
to use or override these methods. 

Suspend procedure Suspend; 

void Suspend (void); 

The application is about to be switched into the background under Multi- 
Finder. If the application’s private scrap is newer than the desk scrap, this 
method sends ConvertPrivate and ScrapConverted messages to the 
clipboard. This method then sends the clipboard window a HideSuspend 
message. 

Resume procedure Resume; 

void Resume (void); 

The application is about to be brought to the foreground under MultiFinder. 
If the desk scrap is newer than the private scrap, this method sends the clip¬ 
board ConvertGlobal, ScrapConverted, and UpdateDisplay mes¬ 
sages to update the contents of the clipboard. This method then sends the 
window a ShowResume message to make it visible. 

Appearance methods 

These methods handle the appearance of the Clipboard window and how 
the contents of the clipboard appear in the window. If you implement your 
own clipboard class, you’ll need to override the UpdateDi splay method. 

Close function Close (quitting: Boolean): Boolean; 

Boolean Close (Boolean quitting); 

The user chose Close from the File menu. Close sends a CloseWind 
message and returns TRUE. 

CloseWind procedure CloseWind (theWindow: CWindow); 

void CloseWind (CWindow *theWindow); 

The user clicked in the window’s close box. This method hides the Clip¬ 
board window and changes the text in the menu item. 

Toggle procedure Toggle; 

void Toggle (void); 

This method opens the Clipboard window if it’s closed or closes it if it’s 
open. The application’s default DoCommand method sends this message. 
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UpdateDisplay procedure UpdateDisplay; 

void UpdateDisplay (void); 

Display the contents of the scrap in the Clipboard window. This method 
supports only TEXT and PICT types of data. This method will work correct¬ 
ly with a private scrap, but if you want to display other kinds of data, you’ll 
need to override this method. 

Accessing methods 

Use these methods to place data in and retrieve data from the desk scrap. If 
your application implements a private scrap, use the PutData and 
GetData methods instead. 

PutClobalScrap procedure PutGlobalScrap (theType: ResType; 

theData: Handle); 

void PutGlobalScrap (ResType theType, Handle theData); 

Put theData of type theType into the desk scrap. Be sure to send an 
EmptyGlobalScrap message before you call this method. 

CetClobalScrap function GetGlobalScrap (theType: ResType; 

theData: Handle): Boolean; 

Boolean GetGlobalScrap (ResType theType, 

Handle theData); 

Get the data of type theType from the desk scrap and put it in the block 
that theData is a handle to. Return TRUE if the method was able to fulfill 
the request, FALSE otherwise. 

TheData must be an allocated handle. The size of the allocated memory 
will grow as needed to fit the data. This is how you would get the TEXT data 
from the desk scrap in THINK Pascal: 

var 

myData: Handle; 
begin 

{ Create a zero-sized handle } 
myData := NewHandle(0); 

gClipboard.GetGlobalData ('TEXT*, myData); 

end 
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DataSize 


Status 


ScrapConverted 


PutData 


And this is how you would get TEXT data from the desk scrap in THINK C: 
Handle myData; 

/* Create a zero-sized handle */ 
myData = NewHandle(0); 

gClipboard->GetGlobalData('TEXT 1 , myData); 

function DataSize (theType: ResType): longint; 
long DataSize (ResType theType); 

Return the number of bytes of data in the clipboard of type theType. If the 
clipboard doesn’t contain any data of the specified type, this method returns 
zero. 


function Status: ScrapStatus; 

ScrapStatus Status (void); 

Return the status of the scrap. This method returns a value that describes the 
relationship between the private scrap and the desk scrap. 


Value 

PRIVATE_SCRAP_NEWER 

GLOBAL_S CRAP_NE WER 

SCRAPS THE SAME 


Meaning 

The information in the private 
scrap is newer than the informa¬ 
tion in the desk scrap. 

The information in the desk scrap 
is newer than the information in 
the private scrap. 

The information in both scraps is 
the same. 


procedure ScrapConverted; 
void ScrapConverted (void); 

Set the internal flags after the scrap has been converted. 

Scrap conversion methods 

Use the PutData and GetData methods to implement Cut, Copy, and 
Paste commands for your application. If your application uses only the desk 
scrap, you can use the PutGlobalScrap and GetGlobalScrap meth¬ 
ods. 


procedure PutData (theType: ResType; theData: Handle); 
void PutData (ResType theType, Handle theData); 

Put theData of type theType into the scrap. The default method puts the 
data in the desk scrap. If your subclass supports a private scrap, you must 
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GetData 


ConvertGlobal 


ConvertPrivate 


EmptyG lobalScrap 
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override this method. After you store your data in the private scrap, be sure 
to send a PrivateChanged message. Before you call this method, be sure 
you send an EmptyScrap method to clear your scrap. 

function GetData (theType: ResType, 
var theData: Handle): Boolean; 

Boolean GetData (ResType theType, Handle *theData); 

Get the data of type theType and put it into a newly created handle. This 
method returns TRUE if the request was successful, FALSE otherwise. If 
your application supports a private scrap, you must override this method. 

Unlike GetGlobalScrap you should not allocate the handle to theData. 
This method will allocate the memory. This is how you’d get data of type 
TEXT in THINK Pascal: 

var 

Handle myData; 
begin 

gClipboard.GetData( 1 TEXT ', myData); 
end; 

And this is how you’d get data of type TEXT in THINK C: 

Handle myData; 

gClipboard->GetData(* TEXT ', SmyData); 

procedure ConvertGlobal; 
void ConvertGlobal (void); 

Convert data in the desk scrap and put it in the private scrap. The default 
method does nothing. If your application supports a private scrap, you must 
override this method. 

procedure ConvertPrivate; 
void ConvertPrivate (void); 

Convert data in the private scrap and put it into the desk scrap. The default 
method does nothing. If your application supports a private scrap, you must 
override this method. 

procedure EmptyGlobalScrap; 
void EmptyGlobalScrap (void) 

Clear the contents of the desk scrap. 
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EmptyScrap procedure EmptyScrap; 

void EmptyScrap (void) 

Clear the contents of the scrap that is the destination of PutData. You 
should call this method before you call PutData. The default method 
clears the global scrap. 

PrlvateChanged procedure PrivateChanged; 

void PrivateChanged (void); 

The data in the private scrap has changed. If you implement a private scrap, 
be sure to send this message to the clipboard after you put new data in your 
private scrap. This method sets the internal flags and sends an 
UpdateDisplay message to the clipboard. Your subclass should not over¬ 
ride this method. 

MakeClipView function MakeClipView (dataType: longint; 

dataHandle: Handle): CPanorama; 

CPanorama *MakeClipView (long dataType, 

Handle dataHandle) 

Make a view to display the clipboard data dataHandle of type dataType. 
This method disposes dataHandle when appropriate. UpdateDi splay 
calls this method to create the right kind of pane for the data you want to 
display in the Clipboard window. 

If you create a subclass of CClipboard, you need to override this method to 
create the kind of pane that you need to display your data. If dataType is 
1 PICT' or * TEXT *, you can call the inherited method. 

Class resources 

The WIND resource for the Clipboard window is in the file TCL 
Resources which contains all of the resources the THINK Class Library re¬ 
quires. 

Resource Description 

WIND 200 Window template for Clipboard window. 
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Introduction 

CCIuster implements an unordered list of objects. 

Heritage 

Superclass CArray 

Subclasses CList 

CStack 


Using CCIuster 

Use a CCIuster object whenever you need to maintain an unordered list of 
objects. Typically, the elements of the list are object references, though you 
can store anything you want in a cluster. The default size for an item in a 
cluster is four bytes, which is large enough to hold a pointer or a handle. 
Several objects in the THINK Class Library use CCIuster objects or descen¬ 
dants of CCIuster to maintain lists. 


Note 

If you need an ordered list of objects, use the CList class in¬ 
stead. 


CCIuster allocates space for each object reference in blocks. By default, a 
block holds three slots. Each slot holds one object reference. CCIuster takes 
care of allocating blocks automatically, though you can change the number 
of slots per block if you like. 
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ICIuster 


Free/Dispose 


DisposeAll 


Disposeltems 


Add 


Variables 

This instance variable has the same value as hi terns but a different type. It’s 
kept for compatibility with the previous version of the THINK Class Library. 

Variable Type Description 

items LongHandle Handle to the items in the 

cluster. 

Methods 

In addition to the insertion, deletion, and searching methods, CCIuster im¬ 
plements iteration methods that let you apply a function to all the objects in 
a cluster. 

Construction and destruction 

procedure ICIuster; 
void ICIuster (void); 

Initialize the cluster. 

procedure Free; 
void Dispose (void); 

Dispose of a cluster, but not the items in it. 

procedure DisposeAll; 
void DisposeAll (void); 

Dispose of a cluster and all the items in it. This method sends a Free (in 
THINK Pascal) or Dispose (in THINK C) message to every item in the clus¬ 
ter. 

procedure Disposeltems; 
void Disposeltems (void); 

Dispose of the items in a cluster, but not the cluster. 

Insertion and deletion 

These methods add objects to and remove objects from the cluster. Remem¬ 
ber that the items in the cluster are not in any particular order. 

procedure Add (theObject: CObject); 
void Add (CObject *theObject); 

Add the Object to the cluster. 
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Remove 


Includes 


Findltem 


Find Item! 


Offset 
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procedure Remove (theObject: CObject); 
void Remove (CObject *theObject); 

Remove theObject from the collection if it is already in the cluster. 

Membership 

These methods let you determine whether a particular item is in the cluster. 

function Includes (theObject: CObject): Boolean; 
Boolean Includes (CObject *theObject); 

Return TRUE if theObject is in the cluster. 

function Findltem (function MyFunc(obj: CObject) : 
Boolean): CObject; 

CObject* Findltem (TestFunc MyFunc); 

Look for an item that satisfies a function. Findltem applies the function 
MyFunc to each item in the list and returns the first one that causes the func¬ 
tion to return TRUE. 

In THINK C, you must declare MyFunc like this: 

Boolean MyBoolFunc (CObject *obj); 

function Findlteml (function MyFuncl(obj: CObject; 
theParam: Ptr); param: Ptr): CObject; 

CObject* Findlteml (TestFuncl MyFuncl, long param) ; 

Look for an item that satisfies a function. Findlteml applies the function 
MyFuncl to each item in the list and returns the first one that causes the 
function to return TRUE. Param is an extra parameter you can pass to 
Findlteml if MyFunc needs more information. 

In THINK C, you must declare MyFunc like this: 

Boolean MyFuncl (CObject *obj, long param); 

function Offset (theObject: CObject): longint; 
long Offset (CObject *theObject); 

Returns the index of theObject in the collection. If theObject is not in 
the collection, Offset returns BAD_INDEX. This is an internal method. In 
most cases you won’t need to use this method. 
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Iteration 

These methods let you apply a function to all of the objects in a cluster. The 
function you apply to the objects in the cluster should not affect the cluster 
itself. 

To apply a message to all the items in a cluster, you need to write a message¬ 
sending function. It’s up to you to make sure that all the items in the cluster 
can respond to the message. 

For example, this is how you send a Draw message to all the items in a clus¬ 
ter, in THINK Pascal: 

procedure Perform_Draw (thePane: CPane; 

area: Ptr) 
begin 

thePane.Draw(RecPtr(area) A ); 

end 

theCluster.DoForEachl (Perform_Draw, @area); 


Note 

RectPtr is defined in TCL. p as A Rect. 


And this is how you send a Draw message to all the items in a cluster, in 
THINK C: 

void Perform_draw(CPane *thePane, Rect *area) 

{ 

thePane->Draw(area); 

1 

myCluster->DoForEachl(Perform_Draw, 

(long)(SmyRect)); 

procedure DoForEach (procedure Proc(theObject: 

CObject)); 

void DoForEach (EachFunc Proc); 

Apply the procedure Proc to each object in the collection. In THINK C, you 
must declare MyFunc like this: 

void MyFunc(CObject *theObject); 
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procedure DoForEachl (procedure Proc(theObject: 
CObject; theParam: Ptr); param: Ptr); 

void DoForEachl (EachFuncl Proc, long param) ; 

Apply the procedure Proc to each object in the collection along with the 
parameter param. In THINK C, you must declare MyFunc like this: 

void MyFuncl(CObject *theObject, long param) ; 
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Introduction 

CCollaborator is an abstract class that implements objects that depend on 
one another. This class provides a mechanism for an object to announce 
changes to other objects. 

Heritage 

Superclass CObject 

Subclasses CBureaucrat 

CCollection 

Using CCollaborator 

This class implements a mechanism that lets an object announce changes to 
other objects. The object that other objects depend on is called the provid¬ 
er. The objects that depend on the provider are called dependents. 

For example, suppose that your program displays the contents of a file as 
different kinds of graphs in different windows. Whenever the data in the file 
change, the windows that display the data should also change. The data file 
is the provider. The graph display windows are the dependents. 

To specify a dependency, send the dependent object a DependUpon mes¬ 
sage with the provider as the argument. When the provider changes, send 
the provider a BroadcastChange message. That method sends each of 
the dependents a ProviderChanged message. 

The BroadcastChange method takes a parameter called reason that lets 
the dependents know why they’re being notified. Reasons are implemented 
as long integers. In C, you can use #def ine directives or enums. In Pascal, 
you can use const declarations. 

Reason names follow two conventions. First, reason names begin with the 
name of their class, without the C. For example, all of CArray’s reasons begin 
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with array. Second, each collaborator subclass has a reason named 
cZassram^LastChange. For example, CArray defines a reason named 
arrayLastChange. Using Last Change ensures that your class and all its 
subclasses have unique reason numbers. Set LastChange to the last reason 
your class defines. When you define a subclass, set the subclass’s first reason 
to the superclass’s LastChange plus one. For example, these are the rea¬ 
son definitions for the CArray class in THINK C: 

enum 

1 

arraylnsertElement = 1, 
arrayDeleteElement, 
arrayMoveElement, 
arrayElementChanged, 

arrayLastChange = arrayElementChanged 

1; 


Note that arrayLastChange is set to arrayElementChanged, the last 
reason. 

These are the reasons for CRunArray, a subclass of CArray: 

enum 

{ 

runArraySizeChanged = arrayLastChange + 1, 
runArrayLastChange = runArraySizeChanged 

1 ; 

Note that CArray’s first (and only) reason is arrayLastChange + 1. 

The examples below illustrate how you might implement the graphing pro¬ 
gram described above. When the data in the data file change, the data file’s 
UpdateData method sends a BroadcastChange message with the rea¬ 
son dataUpdatedL The BroadcastChange method sends each of the 
data file’s graphs, the data file’s dependents, a ProviderChanged method, 
which updates the picture of the data in the graph. 
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This is what it might look like in THINK C: 
enum 

{ myFileUpdated = 1, 
myFilePointAdded, 
myFilePointDeleted, 

myFileLastChange = myFileDeleted 

}; 


void CMyFile::UpdateData (MyDataPtr oldData, 
MyDataPtr newData) 

{ 


BroadcastChange(myFileUpdated, 

(void *) newData 


Be sure to check the class of 
the provider. You can make 
sure that the provider is a 
known object as in the ex¬ 
ample here , or you can 
check for membership with 
the member (). The pre¬ 
ferred way is to check that 
it is a known object. 


void CMyGraphPane::ProviderChanged ( 
CCollaborator *aProvider, 
long reason, void *info) 

{ 

if (aProvider == itsDataFile) 
switch (reason) 

{ 

case myFileUpdated: 

UpdateGraphData(info) ; 
break; 

case myFilePointAdded: 
AddGraphData(info); 
break; 

case myFilePointDeleted: 
DeleteGraphData(info); 
break; 

} 

} 


This is the same example in THINK Pascal: 
const 

myFileUpdated = 1; 

myFilePointAdded = myFileUpdated + 1; 
myFilePointDeleted = myFilePointAdded + 1; 

myFileLastChange = myFileDeleted; 
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procedure CMyFile.UpdateData (oldData, 
newData: MyDataPtr) 
begin 


BroadcastChange(longint(myFileUpdated), 
Ptr (newData) ) ; 


end; 


Be sure to check the class of 
the provider. You can make 
sure that the provider is a 
known object as in the ex¬ 
ample here, or you can 
check for membership with 
the member (). The pre¬ 
ferred way is to check that 
it is a known object. 


procedure CMyGraphPane.ProviderChanged ( 
aProvider: CCollaborator; 
reason: longint; info: Ptr) 
begin 

if aProvider = itsDataFile then 
case MyReason (reason) of 
myFileUpdated: 

UpdateGraphData(info); 
myFi1ePointAdded: 

AddGraphData(info); 
myFilePointDeleted: 

DeleteGraphData(info); 

end 

end; 


Variables 


Variable 

Type 

Description 

itsProviders 

CList 

The objects this col¬ 
laborator depends 



upon. 

it sDependent s 

CList 

The objects that de¬ 
pend upon this col¬ 
laborator. 


Methods 


Creation and destruction 

■Collaborator procedure ICollaborator; 

void ICollaborator (void); 

Initialize a collaborator. This method sets both itsProviders and 
itsDependents to NIL 


Free/Dispose procedure Free; 

void Dispose (void); 

Remove this object from each of its provider’s list of dependents and from 
each of its dependent’s list of providers. Then dispose of its own lists of pro¬ 
viders and dependents. 
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Creating dependency method 

procedure DependUpon (aProvider: CCollaborator); 
void DependUpon (CCollaborator *aProvider); 

This collaborator depends on aProvider. Add this collaborator to 
aProvider’s list of dependents, and add aProvider to this collaborator’s 
list of providers. If either of those lists are NIL, this method creates them be¬ 
fore adding to them. 

procedure CancelDependency (aProvider: CCollaborator); 
void CancelDependency (CCollaborator *aProvidoer); 

This collaborator no longer depends upon aProvider. Remove this collab¬ 
orator from the provider’s dependent list and remove the provider from this 
collaborator’s provider list. 

Change notification methods 

procedure BroadcastChange (reason: long; info: Ptr); 
void BroadcastChange (long reason, void* info); 

Notify this object’s dependents that this object has changed. Reason is an 
integer that describes the type of change. You must define reasons for your 
subclass. Info is a pointer to any additional information needed to respond 
to the change. 

If you want objects that aren’t in a collaborator’s list of dependents to know 
about a change, override this method. For example, CBureaucrat overrides 
this method to notify the bureaucrat’s supervisor, in addition to its depen¬ 
dents, of the change. 

procedure ProviderChanged (aProvider: CCollaborator; 
reason: longint; info: Ptr); 

void ProviderChanged (CCollaborator *aProvider, 
long reason, void* info); 

One of this object’s providers has just changed. Your subclass must override 
this method to respond to each reason it can handle. The default method 
does nothing. AProvider is the provider that changed. Reason is an inte¬ 
ger that describes the type of change. You must define reasons for your sub¬ 
class. Inf o is a pointer to any additional information that your subclass 
might need. 

List update methods 

CCollaborator uses these methods internally to maintain the lists of depen¬ 
dents and providers. Whenever possible, use the DependUpon method in¬ 
stead of these methods. When a dependent is added or removed, 
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AddDependent 


RemoveDependent 


AddProvider 


RemoveProvider 


DependUpon and update both the dependent’s list of providers and the 
provider’s list of dependents. They do the same when a provider is added or 
removed. If you use the functions below, you might damage the collabora¬ 
tors’ lists so that they don’t match. 

procedure AddDependent (aDependent: CCollaborator); 
void AddDependent (CCollaborator *aDependent); 

Add aDependent to this collaborator’s list of dependents. 

procedure RemoveDependent (aDependent: CCollaborator); 
void RemoveDependent (CCollaborator *aDependent); 
Remove aDependent from this collaborator’s list of dependents. 

procedure AddProvider (aProvider: CCollaborator); 
void AddProvider (CCollaborator *aProvider); 

Add aProvider to this collaborator’s list of providers. 

procedure RemoveProvider (aProvider: CCollaborator); 
void RemoveProvider (CCollaborator *aProvider); 

Remove aProvider from this collaborator’s list of providers. 
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Introduction 

CCollection is an abstract class for implementing collections of things. 

Heritage 

Superclass CCollaborator 

Subclasses CArray 

Using CCollection 

CCollection is an abstract class that helps you implement collections of 
things. The class doesn’t provide the implementation of the collection. In 
your subclass, you specify the data structures that implement the list. 

Variables 

The only instance variable in this abstract class is the number of items in the 
collection. Your subclass will need to add at least the instance variable that 
contains or points to the memory that contains the items in your collection. 

Variable Type Description 

numlterns longint The number of items in 

the collection. 

Methods 

procedure ICollection; 
void ICollection (void); 

Initialize the collection. The default method sets the initial number of items 
to 0. 

function GetNumltems: longint; 
long GetNumltems (void); 

Return the number of items in a collection 
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♦- 

IsEmpty 


function IsEmpty: Boolean; 
Boolean IsEmpty (void); 

Return TRUE if the collection has no items. 
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Introduction 

CControl is an abstract class for implementing Macintosh controls. The two 
built-in descendant classes, CButton and CScrollBar, implement the standard 
Macintosh controls. 

Heritage 

Superclass CPane 

Subclasses CButton 

CScrollBar 


Using CControl 

This class describes the common methods for all controls. Scroll bars, but¬ 
tons, check boxes, and radio buttons are descendants of CControl. Although 
you won’t be creating subclasses of CControl (unless you define your own 
kind of control) you should become familiar with these methods. 

Variables 

The only instance variable for this class is a handle to the actual Macintosh 
control. 

Variable Type Description 

macControl ControlHandle Handle to the Macintosh 

control. 


Methods 

You can use these methods with any kind of control, but some methods 
don’t really apply to all controls. For example, it’s possible to set the value of 
a pushbutton or to give a title to a scroll bar, but in most cases these actions 
don’t make sense. 
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Free/Dispose 


SetValue 


CetValue 


SetMaxValue 


GetMaxValue 


SetMin Value 


GetMinValue 


Construction and destruction methods 

The CControl class does not define an initialization method. Each descen¬ 
dant of CControl defines an initialization method that uses CNTL resources 
to specify the type of control. 

procedure Free; 
void Dispose (void); 

Dispose of a control. 

Accessing methods 

procedure SetValue (aValue: integer); 
void SetValue (short aValue); 

Set the value of a control. This method sends a BroadcastChange mes¬ 
sage to all of this object’s dependents with cont rolValueChanged as the 
reason. 

function GetValue: integer; 
short GetValue (void); 

Get the value of a control 

procedure SetMaxValue (aMaxValue: integer); 
void SetMaxValue (short aMaxValue); 

Set the maximum value a control can have. For push buttons, check boxes, 
and radio buttons this value should be 1. 

function GetMaxValue: integer; 
short GetMaxValue (void); 

Get the maximum value a control can take on. 

procedure SetMinValue (aMinValue: integer); 
void SetMinValue (short aMinValue); 

Set the minimum value a control can have. Note that for push buttons, check 
boxes, and radio buttons this value should be 0. 

function GetMinValue: integer; 
short GetMinValue (void); 

Get the minimum value a control can take on. 
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GetTItle 


SetActionProc 


Hide 


Methods 

- ♦ 


procedure SetTitle (aTitle: Str255); 
void SetTitle (Str255 aTitle); 

Set the title of a control. Scroll bars can have titles, but the title is not dis¬ 
played. 

procedure GetTitle (var aTitle: Str255); 
void GetTitle (Str255 aTitle); 

Get the title of a control 

procedure SetActionProc (anActionProc: ProcPtr); 
void SetActionProc (VoidFunc anActionProc); 

Set the action proc of a control. The action proc is called repeatedly while 
the mouse is held down in a control. The control manager distinguishes be¬ 
tween an action proc called when the mouse goes down in a moving indica¬ 
tor Qike a scroll box) and one called when the mouse goes down in a 
stationary part of a control. The default DoClick method sends the action 
proc to the control manager only for mouse hits that are not in a moving in¬ 
dicator. In THINK Pascal, you must declare the action proc like this: 

procedure MyAction (macControl: ControlHandle; 
whichPart: integer); 

In THINK C, you must declare the action proc like this: 

pascal void MyAction (ControlHandle macControl, 
short whichPart); 

If you want an action proc called when the mouse is in a moving indicator, 
you’ll need to override the DoClick method. 


Note 

Be sure you understand action procs and the control man¬ 
ager before you use this method. 


Appearance methods 

These methods control the appearance of controls on the screen. They hide 
and show the control, draw it, move it, and change its size. 

procedure Hide; 
void Hide (void); 

Hide the control. 
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Show 


Activate 


Deactivate 


Offset 


ChangeSize 


Draw 


DrawAII 


Prepare 


procedure Show; 
void Show (void); 

Show the control. 

procedure Activate; 
void Activate (void); 

Make the control active. The control gets an Activate message automati¬ 
cally when its enclosure gets an Activate message. 

procedure Deactivate; 
void Deactivate (void); 

Make the control inactive. The control gets a Deactivate message auto¬ 
matically when its enclosure gets a Deactivate message. 

procedure Offset (hOffset, vOffset: longint; 
redraw: Boolean); 

void Offset (long hOffset, long vOffset, 

Boolean redraw); 

Move the control by hOffset, vOffset pixels. If redraw is TRUE, redraw 
the control after the move. 

procedure ChangeSize (delta: Rect; redraw: Boolean); 
void ChangeSize (Rect *delta. Boolean redraw); 

Change the size of a control. Each component of the rectangle specifies by 
how many pixels to offset each point. Positive numbers mean down and to 
the right. Negative numbers mean up and to the left If redraw is TRUE, re¬ 
draw the control after the change. 

procedure Draw (var area: Rect); 
void Draw (Rect *area); 

Draw the control. The area parameter is ignored. 

procedure DrawAII (var area: Rect); 
void DrawAII (Rect *area); 

Draw the control and all its subviews. 

procedure Prepare; 
void Prepare (void); 

Prepare the port and the coordinate system before drawing. Generally, you 
don’t need to use or override this method. 
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DoClick 


DoThumbDragged 


♦ 


Click response methods 

The CControl class takes care of all the mouse tracking within a control. 

procedure DoClick (hitPt: Point; 

modifierKeys: integer; when: longint); 

void DoClick (Point hitPt, short modifierKeys, 
long when); 

Handle a click in a control. HitPt is the point in frame coordinates. 

Modif ierKeys is the same as the modifier field of an event record. When 
is the time that the mouse went down in ticks. 

The default method handles both simple controls and controls with moving 
indicators and behaves a little differently in each case. 

If the mouse goes down in a part other than a moving indicator: 

• The default method calls the Toolbox routine TrackCont rol 
with the action proc you specified with the SetActionProc 
method. 

• If TrackCont rol returns TRUE (the user clicks and releases the 
mouse in the same part of the control), this method sends a 
DoGoodClick message to the control. 

If the mouse goes down in a moving indicator, like the thumb of a scroll bar: 

• The default method calls the Toolbox routine TrackCont rol 
with no action proc. 

• If the value of the control has changed (the user moved the indi¬ 
cator to a new place), this method sends a DoThumbDragged 
message to the control. 

procedure DoThumbDragged (delta: integer); 
void DoThumbDragged (short delta); 

An indicator in a control has been moved. The DoClick method sends a 
DoThumbDragged message to the control when the user changes the posi¬ 
tion of a control’s indicator. 

The default method does nothing. Controls with indicators should override 
this method. For an example of how to override this method, see 
CScrollBar. DoThumbDragged on page 385. 
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DoCoodClick 


procedure DoGoodClick (whichPart: integer); 
void DoGoodClick (short whichPart); 

The mouse went down and up in the same part of a control. 

The default method does nothing. Subclasses should override this method. 
See the CButton. DoGoodClick on page 195 for an example. 
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26 


Introduction 

This class implements the methods you need to work with a Macintosh data 
file. You can use this class without creating a subclass if you need to read 
raw bytes. If you require a structured file, you should create a subclass of 
CDataFile. 

Heritage 

Superclass CFile 

Subclasses CPNTGFile 

CPictFile 

Using CDataFile 

You can use this class without creating a subclass to read and write the data 
fork of a Macintosh File. After creating an instance of CDataFile, use one of 
the specification methods inherited from CFile to indicate which file you’re 
working with. Then use the Open method to open the file, and use the read¬ 
ing and writing methods to read and write the File. 

Some CDataFile methods use the THINK Class Library’s exception handling 
library if something goes wrong in a file operation. For more information on 
exception handling, see Chapter 8, “Exception Handling.” 


Note 

This version of CDataFile handles errors differently than the 
original version. The old version is now named ODataFile 
and is in the Compatibility foler. 


Variables 

The only instance variable for this class is the refNum of the file. The Macin¬ 
tosh file system uses this number to identify the volume, directory, and File 
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IDataFile 


SetLength 


GetLength 


SetMark 


on disk. To learn more about the Macintosh file system, see Inside Macin¬ 
tosh IV, Chapter 19, “The File Manager.” 

Variable Type Description 

refNum integer The file’s refNum when 

open. 

Methods 

These methods let you open and close data files, read and write data, and 
get information about a file. You need to use the methods inherited from 
CFile to specify which file you want to work with. 

Construction and destruction methods 

procedure IDataFile; 
void IDataFile (void); 

Initialize the data file. 

Accessing methods 

procedure SetLength (aLength: longint); 
void SetLength (long aLength); 

Set the end-of-file marker for this file at aLength. 

function GetLength: longint; 
long GetLength (void); 

Return the length of the file. The file must be open already. 

procedure SetMark (howFar: longint; 
fromWhere: integer); 

void SetMark (long howFar, short fromWhere); 

Specify where subsequent read/write operations will take place. This posi¬ 
tion is called “the mark.” 

HowFar specifies how far in bytes from the fromWhere parameter to set 
the mark. Positive values are offsets toward the end of the file. Negative val¬ 
ues are offsets toward the beginning of the file. FromWhere is one of the 
following: 

fromWhere value Meaning 

f sFromStart from the beginning of the file 

f sFromLEOF from the end of the file 

f s F romMa rk from the current position 
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GetMark 


Open 


Close 


ReadAII 


function GetMark: longint; 
long GetMark (void); 

Return the current position of the mark in markPos. 

Open and close methods 

procedure Open (permission: SignedByte); 
void Open (SignedByte permission); 

Open the file with the given permission. Permission can be one of: 


Permission 

fsCurPerm 
fsRdPerm 
fsWrPerm 
fsRdWrPerm 
fsRdWrShPerm 


Meaning 

same as the current permission 
read permission 
write permission 
read/write permission 
shared read/write permission 


See Inside Macintosh IV, Chapter 19, “The File Manager” for a discussion of 
permissions. 


procedure Close; 
void Close (void); 

Write out any unwritten data and close the file. 

Read and write methods 

function ReadAII: Handle; 

Handle ReadAII (void); 

Read the entire contents of the file into a handle. This method allocates the 
handle. You must pass in a reference to a handle. This example shows how 
to use ReadAII in THINK Pascal: 


var 

theData: Handle; 
begin 

myDataFile.ReadAII(theData); 
end 

And this example shows how to use ReadAII in THINK C: 


Handle theData; 

myDataFile->ReadAll(StheData); 
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ReadSome 


WriteAll 


WriteSome 


procedure ReadSome (info: Ptr; var howMuch: longint); 
void ReadSome (Ptr info, long howMuch); 

Read howMuch bytes into a buffer starting at info. You must allocate the 
space to read the information into. This example shows how to use 
ReadSome in THINK Pascal:: 

var 

myBuffer = packed array [1..128] of char; 
begin 

myDataFile.ReadSome(QmyBuffer, 128); 
end 

And this example shows how to use ReadSome in THINK C: 
char myBuffer[128]; 

myDataFile->ReadSome(myBuffer, 128L); 

procedure WriteAll (contents: Handle); 
void WriteAll (Handle contents); 

Write the contents of the handle to the file. 

procedure WriteSome (info: Ptr; var howMuch: longint); 
void WriteSome (Ptr info, long howMuch); 

Write howMuch bytes from the buffer starting at info. 
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Introduction 

CDecorator implements an object that arranges windows on the screen. 
There is only one instance of this class. 

Heritage 

Superclass CObject 

Subclasses None 

Using CDecorator 

CDecorator gives you methods for arranging windows on the screen. There 
is only one instance of CDecorator which is stored in the global variable 
gDecorator. 

After creating and initializing a new window, send it in a PlaceNewWindow 
message to the decorator. The decorator makes the window a bit smaller 
than the main screen and offsets it down and to the right. Using the decora¬ 
tor is entirely optional. 

You can create a subclass of CDecorator if you like. For instance, you might 
want a decorator that implements window tiling. Be sure to override the 
MakeDecorator method in your application subclass to initialize your 
decorator and to store the decorator in the global variable gDecorator. 

Variables 

The global decorator object, created in the application method 
MakeDecorator, is stored in the global variable gDecorator. 

Global variable 

Variable Type Description 

gDecorator CDecorator The window-dressing object. 
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I Decorator 


PlaceNewWindow 


StaggerWindow 


CenterWindow 


GetWCount 


Instance variables 


Variable 

Type 

Description 

wCount 

integer 

The number of new windows 
placed 

index 

integer 

Index for offsetting windows 

wWidth 

integer 

Width of a window in pixels 

wHeight 

integer 

Height of a window in pixels 

hLocation 

integer 

Horizontal location for next 
window 

vLocation 

integer 

Vertical location for next win¬ 
dow 


Methods 

procedure IDecorator; 
void IDecorator (void); 

Initialize the decorator. The application method MakeDecorator creates 
the global decorator and sends it this message. 

procedure PlaceNewWindow (theWindow: CWindow); 
void PlaceNewWindow (CWindow *theWindow); 

Place theWindow on the screen. The default method makes it fill up most 
of the screen and calls StaggerWindow to position it. . 

procedure StaggerWindow (theWindow: CWindow); 
void StaggerWindow (CWindow *theWindow); 

Position a new window on the screen, offset down and to the right of the 
last window the decorator placed. 

procedure CenterWindow (theWindow: CWindow ); 
void CenterWindow (CWindow *theWindow); 

Center the window specified by theWindow on the main screen. If 
theWindow is a modal dialog, this method tries to put it in the top third of 
the main screen. This method does not increment wCount or change any of 
the instance variables. 

function GetWCount: integer; 
short GetWCount (void); 

Return the number of windows the decorator has put on the screen. You can 
use this value to give your untitled windows sequential numbers like “Unti¬ 
tled-1.” 
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Introduction 

CDesktop implements a view that occupies the entire screen. This view 
serves as the top of the visual hierarchy and the enclosure for all windows. 
Normally, there is only one instance of CDesktop. 

Heritage 

Superclass CView 

Subclasses CFWDesktop 

Using CDesktop 

The most common way you’ll use the desktop is as the enclosure for your 
windows. Your application should not send messages to the desktop. In¬ 
stead, you should rely on higher level objects like windows and directors to 
send messages to it. 

CFWDesktop is a subclass of CDesktop which implements a desktop that 
supports floating windows. CFWDesktop is described on page 289. 

The desktop is stored in the global variable gDesktop. The CApplication 
method MakeDesktop creates an instance of the CDesktop and stores it in 
that variable. 

Variables 

The global variable gDesktop holds a pointer to the single instance of the 
desktop. Use this variable to specify the enclosure for your application’s 
windows. 

Global variable 

Variable Type Desktop 

gDesktop CDesktop The single instance of the 

desktop 
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IDesktop 


Free/Dispose 


Show 


Hide 


Activate 


Deactivate 


Instance variables 
Variable 

bounds 

itsWindows 

topWindow 


Type 

Rect 

CList 

CWindow 


Desktop 

Boundaries of the desktop 
List of windows 
Top-most application win¬ 
dow 


Methods 

Construction and destruction methods 

procedure IDesktop (aSupervisor: CBureaucrat); 
void IDesktop (CBureaucrat *aSupervisor); 

Initialize the desktop. The default method opens a GrafPort that your ap¬ 
plication uses as its desktop. The desktop’s supervisor should be the appli¬ 
cation, stored in the global variable gApplication. 

procedure Free; 
void Dispose (void); 

Dispose of the desktop and send this message to all of the desktop’s win¬ 
dows. 

Appearance methods 

procedure Show; 
void Show (void); 

Makes a desktop visible by showing all of its windows. This method sends a 
Show message to all of the desktop’s windows. 

procedure Hide; 
void Hide (void); 

Hide a desktop by hiding all of its windows. This method sends a Hide mes¬ 
sage to all of the desktop’s windows. 

procedure Activate; 
void Activate (void); 

Activate the desktop by activating the top window. This method sends an 
Activate message to the desktop’s top window. 

procedure Deactivate; 
void Deactivate (void); 

Deactivate a desktop by deactivating its top window. This method sends a 
Deactivate message to the desktop’s top window. 
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ReallyVisible 


DispatchClick 


function ReallyVisible: Boolean; 

Boolean ReallyVisible (void); 

Return TRUE if the desktop is visible. 

Mouse methods 

procedure DispatchClick (var macEvent: EventRecord); 
void DispatchClick (EventRecord *macEvent); 

If the user clicks the mouse anywhere, find out where the mouse went 
down, and send the appropriate message to the object the click is intended 
for. If the top window is modal, and the mouse did not go down in the menu 
bar, this method beeps and does not process the click. 

This method uses what the Macintosh Toolbox routine FindWindow re¬ 
turns to determine what message to send to which object. 


Part 

inDesk 


inSysWindow 


inMenuBar 


inContent 


Action 

If the mouse goes down in the desktop, 
this method sends a DoClick message to 
the desktop. The default DoClick meth¬ 
od does nothing. 

If the mouse goes down in a system win¬ 
dow, this method calls the Toolbox rou¬ 
tine SystemClick. 

If the mouse goes down in the menu bar, 
this method calls the Toolbox routine 
MenuSelect. This method then sends a 
FindCmdNumber message to the bar¬ 
tender to convert the menu selection into 
a command number. This command num¬ 
ber is sent to the gopher in a DoCommand 
message. 

If the mouse goes down in the content re¬ 
gion of a window and the window is not 
active, this method sends the window a 
Select message. If the window is al¬ 
ready active and can receive clicks, this 
method sends the window a 
DispatchClick message which will 
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DoMouseUp 


DispatchCursor 


AdjustCursor 


Contains 


eventually send a DoClick message to a 
pane or the window itself. 

If the mouse goes down in the drag region 
(the title bar), this method sends the win¬ 
dow a Drag message. 

If the mouse goes down in the window’s 
grow region (the lower right corner), this 
method sends the window a Resize 
message. 

If the mouse goes down and up in the 
window’s close box, this method sends it 
a Close message. 
inZoomln, inZoonOut If the mouse goes down and up in the 

window’s zoom box, this method sends it 
a Zoom message. 

procedure DoMouseUp (macEvent: EventRecord); 
void DoMouseUp (EventRecord *macEvent); 

Handle a mouse up event in the desktop. The default method does nothing. 

procedure DispatchCursor (where: Point; 
mouseRgn: RgnHandle); 

void DispatchCursor (Point where, RgnHandle mouseRgn) ; 

Set the cursor for the view the cursor is in. If the cursor is over an active win¬ 
dow, this method sends a DispatchCursor message to the window. If the 
cursor is in the menu bar, this method sets it to the arrow. If the cursor is not 
in the menu bar or in an active window, this method sends an 
AdjustCursor message to the desktop. You should not override this 
method. 

procedure AdjustCursor (where: Point; 
mouseRgn: RgnHandle); 

void AdjustCursor (Point where, RgnHandle mouseRgn) ; 

Adjust the cursor shape when the mouse is in an insignificant part of the 
desktop. The default method sets the cursor to an arrow. 

function Contains (thePoint: Point): Boolean; 

Boolean Contains (Point thePoint); 

Return TRUE if thePoint is within the bounds of the desktop. 


inDrag 


inGrow 


inGoAway 
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HitSamePart 


AddWind 


RemoveWInd 


SelectWind 


ShowWind 


HideWind 


DragWind 


UpdateWindows 
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function HitSamePart (var pointA, pointB: Point): 
Boolean; 

Boolean HitSamePart (Point pointA, Point pointB); 

Return TRUE if pointA and pointB are reasonably close together. “Rea¬ 
sonably close” means that the two points are within REASONABLY_CLOSE 
pixels. 

Window methods 

You do not have to use any of these methods yourself. Directors, objects that 
manage the interaction between windows and the desktop, take care of 
sending most of these messages. 

procedure AddWind (theWindow: CWindow); 
void AddWind (CWindow *theWindow); 

Add theWindow to the desktop’s window list. 

procedure RemoveWind (theWindow: CWindow); 
void RemoveWind (CWindow *theWindow); 

Remove theWindow from the desktop’s window list. 

procedure SelectWind (theWindow: CWindow); 
void SelectWind (CWindow *theWindow); 

Select theWindow and bring theWindow to the front. 

procedure ShowWind (theWindow: CWindow); 
void ShowWind (CWindow *theWindow); 

Make theWindow visible on the desktop. 

procedure HideWind (theWindow: CWindow); 
void HideWind (CWindow *theWindow); 

Hide theWindow. 

procedure DragWind (theWindow: CWindow; 
macEvent: EventRecord); 

void DragWind (CWindow *theWindow, 

EventRecord *macEvent); 

Drag theWindow on the desktop, 
procedure UpdateWindows; 
void UpdateWindows (void); 

Send an Update message to each of the desktop’s windows. 
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GetTopWindow 

GetBounds 

GetAperture 

Prepare 

Cleanup 


Accessing methods 

function GetTopWindow: CWindow; 

CWindow* GetTopWindow (void); 

Get the frontmost window. 

procedure GetBounds (theBounds: Rect); 
void GetBounds (Rect *theBounds); 

Get the bounds of the desktop. 

procedure GetAperture (var theAperture: LongRect); 
void GetAperture (LongRect *theAperture); 

Get the visible portion of the desktop. This method returns the bounds of 
the desktop since all of the desktop is always visible. 

Calibration methods 

procedure Prepare; 
void Prepare (void); 

Set the port to the desktop port. You should not use or override this method. 

Cleanup method 

procedure Cleanup; 

This method is in THINK Pascal only. This method does nothing, but 
CFWDesktop overrides it to move THINK Pascal windows to the back. For 
more information see CFWDesktop. Cleanup on page 292. THINK C 
doesn’t use this method since CFWDesktop doesn’t need to move THINK C 
windows to the back. 


248 


Object-Oriented Programming 



CDirector # 
29 


Introduction 

CDirector is an abstract class for implementing a window that can handle 
commands. Directors implement communication between the application 
and a window. 

Heritage 

Superclass CDirectorOwner 

Subclasses CDocument 

CClipboard 
CTearOffMenu 


Using CDirector 

A director is an abstract class that manages the communication between the 
application and a window. Any time you want to display a window, it must 
be related to a director. 

In most cases, you’ll use the CDocument subclass to display and manipulate 
data stored in a file in a window. The only time you’ll create a subclass of 
CDirector is when you need a special kind of window like a status window, 
a sub window, or a tear-off menu. 


Note 

The class CTearOffMenu implements a tear-off menu as a 
subclass of CDirector. 


When a window belonging to a director becomes the active window, the go¬ 
pher points to the bureaucrat specified by the director’s itsGopher in¬ 
stance variable. When the window becomes inactive, the gopher points to 
the application. 

When the switchboard processes a window-related event (such as an update 
event), it sends the message to the window which in turn sends the message 
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IDirector 


to the director. When the user chooses a command from the menu, the 
switchboard sends the DoCommand message to the gopher. 

The supervisor of a director must be the application. The supervisor of a 
window must be a subclass of CDirector. 

Variables 

Global variable 

The global variable gGopher points to the current bureaucrat which is usu¬ 
ally a descendant of CDirector. When a window becomes active, gGopher 
points to the bureaucrat specified in the director’s itsGopher instance 
variable. When there are no active directors, gGopher points to the applica¬ 
tion. 


Variable Type Description 

gGopher CBureaucrat The current bureaucrat. 

Instance variables 

The instance variable itsGopher usually points to the main pane of a win¬ 
dow. When the director becomes active, the bureaucrat specified in 
itsGopher becomes the gopher. 


Variable 

itsWindow 

active 

itsGopher 


act ivateWindOnResume 


Type 

CWindow 

Boolean 

CBureaucrat 


Boolean 


Description 

Window that the di¬ 
rector controls 
TRUE if the director 
is active 

Bureaucrat to make 
the gopher when 
the director is acti¬ 
vated. 

TRUE, if the director 
activates its window 
when the program is 
resumed 


Methods 

Creation and destruction 

procedure IDirector (aSupervisor: CDirectorOwner); 
void IDirector (CDirectorOwner *aSupervisor); 

Initialize the director. This method adds the director to aSupervisor’s list 
of directors. By default, the director has no window and is not active. The 
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Free/Dispose 


GetWindow 


FindViewBylD 


OwnsWindow 


DoCommand 
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itsGopher instance variable is set to this object. Your director subclass 
must create the window for the director. Your director subclass should call 
the inherited method to initialize the director. 

procedure Free; 
void Dispose (void); 

Dispose of the director. This method sends a Free or Dispose message to 
the director’s window (if it has one) and removes the director from the su¬ 
pervisor’s list of directors. Your subclass must call the inherited method to 
make sure that the director is disposed of properly. 

Accessing method 

function GetWindow: CWindow; 

CWindow* GetWindow (void); 

Return the window that the director controls. 

function FindViewBylD (aViewID: longint): CView; 

CView* FindViewBylD (long aViewID); 

Within the director’s window, locate the view with id a View ID. 

function OwnsWindow (aWindow: CWindow): Boolean; 
Boolean OwnsWindow (CWindow *aWindow); 

Return TRUE if this director owns aWindow. The director owns the window 
if the window’s supervisor is this object. 

Command methods 

procedure DoCommand (theCommand: longint); 
void DoCommand (long theCommand); 

Handle a command. The default method handles this command: 

Command Description 

cmdClose Send a Close (FALSE) message to the 

director 

Your director class will usually override this method. You should handle 
your own commands first, then call the inherited method to get the generic 
effects. 
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UpdateMenus 

Activate 


Deactivate 

ActivateDirector 

DeactivateDirector 

Suspend 


procedure UpdateMenus; 
void UpdateMenus (void); 

If a window is associated with the director, this method enables the Close 
command (cmdClose). 

Appearance methods 

procedure Activate; 
void Activate (void); 

A director is becoming active. If the director’s window is not a floating win¬ 
dow, sends a BecomeGopher (TRUE) message to itsGopher. This meth¬ 
od sets gSleepTime to 0 to force an idle event and sends an 
ActivateDirector message to the director’s supervisor. 

procedure Deactivate; 
void Deactivate (void); 

A director is becoming inactive. If the director is the gopher, send a Be¬ 
comeGopher (TRUE) message to the director’s supervisor. This method 
sends as DeactivateDirector message to the director’s supervisor. 

procedure ActivateDirector (aDirector: CDirector); 
void ActivateDirector (CDirector *aDirector); 

A director owned by this director is becoming active. This method calls the 
inherited method to make aDirector the frontmost director and sends an 
ActivateDirector message to this director’s supervisor. 

procedure DeactivateDirector (aDirector: CDirector); 
void DeactivateDirector (CDirector *aDirector); 

A director owned by this director is becoming inactive. This method calls the 
inherited method and sends a DeactivateDirector message to this di¬ 
rector’s supervisor. 

procedure Suspend; 
void Suspend (void); 

The application is being suspended. This method calls the inherited method 
to send a Suspend message to all of the supervisor’s directors. If this direc¬ 
tor is active, and if it owns an active window, it sends the window a Deac¬ 
tivate message. The director remains active even though the application 
is suspended. 
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Resume 


Close 


CloseWInd 


ActivateWind 


DeactivateWInd 
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procedure Resume; 
void Resume (void); 

The application is being resumed. This method calls the inherited method to 
send a Resume method to all of the supervisor’s directors. If the director is 
active and the director owns a window, send the window an Activate 
message. 

The default method sends the director an Activate message. 

function Close (quitting: Boolean): Boolean; 

Boolean Close (Boolean quitting); 

Close a director. This method calls the inherited method to close all of the di¬ 
rectors that the supervisor owns (including this one). If all of the directors 
closed, this method calls Free or Dispose and returns TRUE, otherwise it 
returns FALSE. 

Window methods 

procedure CloseWind (theWindow: CWindow); 
void CloseWind (CWindow *theWindow); 

This method calls Close (FALSE). If theWindow is not the window 
owned by this director, it sends a Dispose or a Free message to theWindow. 

If you want a click in the window’s close box to mean something other than 
closing the director, override this method. For instance, you might want to 
override this method so it hides the window instead of closing it. See CClip- 
board’s CloseWind method on page 212 for an example. 

procedure ActivateWind (theWindow: CWindow); 
void ActivateWind (CWindow *theWindow); 

The window owned by the director has been activated You generally won’t 
need to use or override this method in your director subclasses unless you 
want to do something to theWindow (and not the director) when it be¬ 
comes active. To perform specific actions at activate time, override the 
Activate method instead. 

procedure DeactivateWind (theWindow: CWindow); 
void DeactivateWind (CWindow *theWindow); 

The window owned by the director is becoming inactive. You generally 
won’t need to use or override this method in your director subclasses unless 
you want to do something to theWindow (and not the director) when it be¬ 
comes deactivated. To perform some specific actions at deactivate time, 
override the Deactivate method instead. 
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Is Active 


ProviderChanged 


function IsActive: Boolean; 

Boolean IsActive (void); 

Returns TRUE if the director is active; FALSE otherwise. You should not 
override this method. 

Change notification method 

This method overrides a method in CCollaborator. For more information, see 
CCollaborator on page 223. 

procedure ProviderChanged (aProvider: CCollaborator; 
reason: longint; info: Ptr); 

void ProviderChanged (CCollaborator *aProvider, 
long reason, void* info); 

One of this director’s providers or subordinates has just changed. This meth¬ 
od handles the reason bureaucrat Is Gopher by updating the instance 
variable itsGopher. If your subclass handles other reasons, it should over¬ 
ride this method and call the inherited method. 

AProvider is the provider or subordinate that changed. In this case it is the 
bureaucrat that is becoming the gopher Reason is an integer that describes 
the type of change. In this case, bureaucrat IsGopher is the only reason 
handled. Inf o is a pointer to any additional information that a subclass 
might need. This method does not use info, and passes it along in a call to 
the inherited method. 
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Introduction 

CDirectorOwner is an abstract class for objects that own directors, which are 
objects that manage windows. 

Heritage 

Superclass CBureaucrat 

Subclasses CApplication 

CDirector 

Using CDirectorOwner 

CDirectorOwner is an abstract class for objects that own directors. A director 
is an object that manages the communication between an application and a 
window. 

CDirectorOwner has two subclasses: CApplication and CDirector. An appli¬ 
cation needs to inform its directors when the application is suspending, re¬ 
suming, or quitting. If your application implements multi-window 
documents, use an object of class CDocument as the main document and 
objects of class CDirector as the subwindows. The subwindows should be 
owned by the document object. 
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IDirectorOwner 


Dispose/Free 


AddDirector 


RemoveDirector 


Activate Director 


DeactWateD Irector 


Suspend 


Variables 

Variable Type Description 

itsDirectors CList List of the directors this 

object owns. 

active Boolean TRUE if any director is ac¬ 

tive. 

Methods 

Creation and destruction 

procedure IDirectorOwner (aSupervisor: 

CDirectorOwner); 

void IDirectorOwner (CDirectorOwner *aSupervisor); 
Initialize the owner. This methodsets itsDirectors to NULL. 

procedure Free; 
void Dispose (void); 

Dispose of this object and all the directors it owns. 

Insertion and deletion methods 

procedure AddDirector (aDirector: CDirector); 
void AddDirector (CDirector *aDirector); 

Add a new director to the director list. 

procedure RemoveDirector (aDirector: CDirector); 
void RemoveDirector (CDirector *aDirector); 

Remove a director from the director list. 

Appearance methods 

procedure ActivateDirector (aDirector: CDirector); 
void ActivateDirector (CDirector *aDirector); 

A director that this object owns has been activated. Sets active to TRUE. 

procedure DeactivateDirector (aDirector: CDirector); 
void DeactivateDirector (CDirector *aDirector); 

A director that this object owns has been deactivated. Sets active to FALSE. 

procedure Suspend; 
void Suspend (void); 

Notify this object’s directors that the application is suspending. Send a Sus¬ 
pend message to all directors. 
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Resume 


Quit 


Close 


-—-- 4 

procedure Resume; 
void Resume (void); 

Notify this object’s directors that the application is resuming. Send a Resume 
message to all the directors. 

function Quit: Boolean; 

Boolean Quit (void); 

The application is about to quit. This method is the same as calling 
Close(TRUE) . 

function Close (fQuitting: Boolean): Boolean; 

Boolean Close (Boolean fQuitting); 

Try to close all the directors that this object owns. If they all close, this meth¬ 
od returns TRUE. If any director doesn’t close, this method stops closing 
directors and returns FALSE. Set fQuitting to TRUE if you are quitting the 
application. 
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31 


Introduction 

CDocument is the main class for presenting and manipulating information. 
You can think of a document as the association of a window, a file, and a set 
of panes. 

Your application must create a subclass of CDocument. 

Heritage 

Superclass CDirector 

Subclasses You must create a subclass of CDocument 

Using CDocument 

CDocument is one of the classes you need to override to implement an ap¬ 
plication in the THINK Class Library. You can think of a document as a file 
that you view through a window. A better way to think about a document is 
that it is the essence of a Macintosh application. It is anything that you can 
display and manipulate inside a window. 

The document is where your application draws and displays its data. Since 
documents are descendants of CDirector, all documents have windows asso¬ 
ciated with them. Most documents also have an associated file. Neither the 
window nor the file are created automatically. You must create them your¬ 
self in your document’s initialization method. 

Your document class should override these methods: 

initialization method OpenFile 

Free DoSave 

DoCommand DoSaveAs 

NewFile Revert 

Your document class must have an initialization method. If your subclass de¬ 
fines new instance variables, this is the method that sets them up. By con- 
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vention, the name of your initialization method should be I Your Doc, where 
YourDoc is the name of your document class. Your initialization method 
should call IDocument. The supervisor of a document is always 
gApplication. 

If your application allocates memory, you should also override the Free or 
Dispose method to deallocate it. Be sure that your method calls the inherit¬ 
ed method to make sure that the document is disposed of properly. 


Note 

You do not need to dispose of the window or file associat¬ 
ed with a document. The default Free or Dispose meth¬ 
od does that for you. 


Your document class’s DoCommand method does most of the work in your 
application. When a window is active, the switchboard sends all commands 
to the document first (it’s the gopher), and if the document can’t handle it, 
the application class tries to handle it. Your document class should handle all 
the commands it knows about, and call the inherited method when it can’t. 


Note 

Be sure that your DoCommand method or that one of the 
methods it invokes sets the instance variable dirty to 
TRUE when there has been a change to the document. 


Your document class gets a NewFile message when you choose New from 
the File menu. This method needs to create a window and attach the panes 
for it. The NewFile method doesn’t need to create a file until you try to 
save the document. 

Your document gets an OpenFile message when you choose Open... 
from the File menu. The OpenFile method has one argument: a Macintosh 
SFReply record. When you get the OpenFile message, you can be sure 
that the SFReply record is properly filled in. Your OpenFile message 
needs to create an instance of a file object (usually of class CDacaFile). You 
can send your file any of several read messages to get its contents. Your 
OpenFile method also needs to create a window to display the contents of 
the file, just as your NewFile method does. 

When the you choose Save from the File menu, your document gets a 
Do Save message. Your Do Save method should write the contents of its file 
to disk. The file object is stored in the instance variable itsFile. 
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When the you choose Save As... from the File menu, your document gets a 
DoSaveAs message. This method takes an SFReply record, and you can 
be sure that it is properly filled in. Your document class needs to override 
this method to write its data to a file. 

If your application supports the Revert command, you should implement 
DoRevert method. Your implementation might close the file without sav¬ 
ing, then open the file again. 

Variables 

Global variables 

The global variable gGopher points to the current bureaucrat which is usu¬ 
ally a document. When a window becomes active, gGopher points to the 
document that owns it. When there are no active documents, gGopher 
points to the application. 

The supervisor of every document is the application. 


Variable 

Type 

Description 

gGopher 

CBureaucrat 

The current bureaucrat. 

gApplication 

CApplication 

The application 

Instance variables 

Variable 

Type 

Description 

itsMainPane 

CPane 

The document’s main 
pane. NIL if the document 
has no main pane. The 
main pane’s enclosure 
should be itsWindow, an 
instance variable inherited 
from CDirector. 

itsFile 

CFile 

The file associated with 
this document. NIL if doc¬ 
ument has no file. 

lastTask 

CTask 

The last task this docu¬ 
ment was notified as being 
completed 

undone 

Boolean 

TRUE if the last task was 
undone. 

itsPrinter 

CPrinter 

The printer object associ¬ 
ated with this document. 
NIL if document is not 
printable 
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IDocument 


Free/Dispose 


Notify 


Variable Type 

dirty Boolean 


pageWidth integer 
pageHeight integer 


Description 

TRUE if document has 
been altered. 

The width of a page. 
The height of a page. 


Methods 

Construction and destruction methods 

procedure IDocument (aSupervisor: CApplication; 
printable: Boolean); 

void IDocument (struct CApplication *aSupervisor, 
Boolean printable); 

Initialize the document. ASupervisor must be the gApplication. If the 
value of printable is TRUE, this method calls MakePrinter to create an 
instance of CPrinter and stores it in the itsPrinter instance variable. 


procedure Free; 
void Dispose (void); 

Dispose of the document and memory it allocated. This method sends a 
Free or a Dispose message to itsFile, lastTask, and itsPrinter 
if they were allocated. The Close method usually calls this method. If your 
document subclass allocates memory (such as a pane for it sMa inPane) 
your method must dispose of it, then you must call the inherited method to 
dispose of the rest of the document. 

Command methods 

procedure Notify (theTask: CTask); 
void Notify (CTask *theTask); 

A subordinate has completed a task. The default method disposes the cur¬ 
rent lastTask and stores theTask in the instance variable lastTask. 
This method sets undone to FALSE and dirty to TRUE. 
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DoCommand 


UpdateMenus 


procedure DoCommand (theCommand: longint); 
void DoCommand (long theCommand); 

Handle a document-related command. The default method handles these 
commands: 


Command 

cmdClose 

cmdSave 

cmdSaveAs 


cmdRevert 


cmdPageSetup 

cmdPrint 

cmdUndo 


Action 

Send a Close message to the document. 
Set the cursor to the watch cursor and 
send a DoSave message to the document. 
Send a DoSaveFileAs message to the 
document. The default DoSaveFileAs 
method sets the cursor to a watch. 

Display a “Do you really want to revert?” 
alert. If you respond OK, set the cursor to 
the watch cursor and send a DoRevert 
message to the document. 

If the document is printable, send a 
DoP age Set up to the document. 

If the document is printable, send a 
DoPrint message to the document. 

If there is a last task, send either a Redo or 
an Undo message to the task. Then send 
an UpdateUndo message to the docu¬ 
ment. 


Your document class will usually override this method. You should handle 
your own commands first, then call the inherited method to handle the de¬ 
fault commands. 


procedure UpdateMenus; 
void UpdateMenus (void); 

Update the menu items right before they appear on the screen. The default 
method enables the following commands: 


Command 

cmdSaveAs 

cmdSave 

cmdRevert 

cmdPageSetup 

cmdPrint 

cmdUndo 


Enabled if... 

always 

the document is dirty, 
a file is associated with the document and 
it’s dirty. 

the document is printable, 
the document is printable, 
there is a last task to undo. 
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Your document class should override this method to enable the appropriate 
commands for your document. Be sure you call the inherited method before 
you enable your document’s commands. 

Appearance Methods 

Close function Close (quitting: Boolean): Boolean; 

Boolean Close (Boolean quitting); 

A document is being closed. This method sends a Conf irmClose message 
to the document. If the result is TRUE, it sends a Close message to 
itsFile (if it has one). The quitting parameter tells the 
Conf irmClose method whether to ask to save before “closing” or “quit¬ 
ting.” If the document was actually closed, this method returns TRUE. Other¬ 
wise it returns FALSE. 

CloseWInd procedure CloseWind (theWindow: CWindow); 

void CloseWind (CWindow *theWindow); 

Close the specified window. The default method sends a Close message to 
the document. If you want to be able to close windows without actually 
closing a file, you should override this method. Otherwise, your document 
class should not override this method. 

ConfirmClose function Conf irmClose (quitting: Boolean) : Boolean; 

Boolean ConfirmClose (Boolean quitting); 

Display a “Save before closing?” or “Save before quitting?” dialog. If you an¬ 
swer yes, send a DoSave to the document and return TRUE. If you answer 
no, just return TRUE. If you answer Cancel, return FALSE. If your document 
does not have a file, your document class should override this method with 
a method that always returns TRUE. 

File Creation 

NewFile procedure NewFile; 

void NewFile (void); 

Open a new file. The default method does nothing. Your 
CreateDocument method in your application class should send a 
NewFile message to the document it creates. Your document class should 
override this method to do the following: 

• Create a new window and assign it to it sWindow 

• Create a new file and assign it to itsFile 

• Create the panes you need and assign the main pane to 
itsMainPane 
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OpenFile 


MakePrinter 


Paginate 


PageCount 
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procedure OpenFile (macSFReply: SFReply); 
void OpenFile (SFReply *macSFReply); 

Open an existing file. The default method does nothing. Your 
OpenDocument method in your application class should send an 
OpenFile message to the document it creates. Your document class should 
override this method and do the following: 

• Create a new window and assign it to its Window 

• Open the file specified in macSFReply and assign it to 
itsFile 

• Create the panes you need and assign the main pane to 
itsMainPane 

• Display the contents of the file in the pane 


Note 

To learn how to specify a file, see the class CFile. To learn 
how to read and write from a data file, see the class CData- 
File on page 237. 


Printing Methods 

procedure MakePrinter; 
void MakePrinter (void); 

Make the printer object for this document. For more information on printer 
objects, see page 363- If you create subclass of CPrinter, you should override 
this method to create an object of your class. 

procedure Paginate; 
void Paginate (void); 

Send a Paginate message to itsMainPane if its not NIL, otherwise send 
a ResetPagination message to itsPrinter. 

function PageCount: integer; 
short PageCount (void); 

Return the number of pages in the document. This method sends a GetStrip- 
Count message to itsPrinter to find out how many pages the document will 
take. If there are too many pages (more than 999), it raises an exception. 

If the document doesn’t have a CPrinter object associated with it, this meth¬ 
od returns zero. 
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AboutToPrint 


PrintPageOfDoc 

DonePrinting 


DoSave 

DoSaveAs 

DoRevert 


procedure AboutToPrint (var firstPage, lastPage: 
integer); 

void AboutToPrint (short *firstPage, short *lastPage); 
Check the range of pages to be printed. The default method changes 
lastPage to be equal to PageCount. Your document class should over¬ 
ride this method to do whatever is appropriate for your application. This is 
the place where the document can request information about the page size 
from itsPrinter. 

procedure PrintPageOfDoc (pageNum: integer); 
void PrintPageOfDoc (short pageNum); 

Print the specified page. The default method sends a PrintPage message 
to it sMa inPane if it’s not NIL. 

procedure DonePrinting; 
void DonePrinting (void); 

Printing is complete. The PrintPageRange method in CPrinter sends this 
message when the print loop is over. This method sends a DonePrinting 
message to it sMa inPane. 

Filing Methods 

function DoSave: Boolean; 

Boolean DoSave (void); 

Save the document under its current name and return TRUE if successful. 
The current file is available through the instance variable itsFile. The de¬ 
fault method does nothing. Your document class must override this method. 

function DoSaveAs (macSFReply: SFReply): Boolean; 
Boolean DoSaveAs (SFReply *macSFReply); 

Save the document under a new name and return TRUE if successful. The 
macSFReply record specifies where to write the file. The default method 
does nothing. Your document class must override this method. 

procedure DoRevert; 
void DoRevert (void); 

Revert to the last saved version of this document. The default method does 
nothing. If you want your application to support the Revert command, 
you’ll have to override this method. 
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DoSaveFileAs 


PickFileName 


GetName 


UpdateUndo 


function DoSaveFileAs: Boolean; 

Boolean DoSaveFileAs (void); 

Respond to a Save As... command and return TRUE if successful. This meth¬ 
od sends a PickFileName message to the document. If you provide a 
good file name, it sends a DoSaveAs message to the document. Since this 
method implements the standard Save As... command through two other 
messages, you won’t need to override this method. 

procedure PickFileName (var macSFReply: SFReply); 
void PickFileName (SFReply *macSFReply); 

Display a standard get file dialog to get a new file name. PickFileName 
uses the GetName method to specify the default name. 

procedure GetName (var theName: Str255); 
void GetName (Str255 theName); 

Get the name of the document. If there is a file associated with the docu¬ 
ment, this method returns the name of the file. If there is no file associated 
with the document, but there is a window associated with it, it returns the ti¬ 
tle of the window. If there is neither a file nor a window associated with the 
document, this method returns a null string. 

Undo methods 

procedure UpdateUndo; 
void UpdateUndo (void); 

Update the Undo/Redo menu item to have the correct wording. Default 
method sends a GetName Index message to the lastTaskto find its string 
in the STRtaskNames STR# resource. Your document class should not 
override this method. 

Class Resources 

Resource 

STRprompt 150 

ALRTrevert 150 
ALRTsaveChanges 151 

STRtaskNames 130 
STRcommon 128 


Description 

STR resource ID for 
PickFileName prompt string 
Revert to saved alert 
Save changes bef ore close/quit 
alert 

STR# resource ID for task names 
STR# resource for commonly 
used strings 
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Introduction 

CEditText implements a pane that displays text. This class uses the Macin¬ 
tosh TextEdit routines. 

Heritage 

Superclass 
Subclasses 

Using CEditText 

Use CEditText whenever you need to display unformatted text. An edit text 
pane is usually the panorama in a scroll pane so you can scroll through the 
text. The DoCommand method of an edit text pane handles all the common 
text editing commands such as cutting and pasting, font selection, line spac¬ 
ing, etc. The Specify method, inherited from CAbstractText, on page 120, 
lets you choose whether the user can edit and copy your text pane’s text. 

CEditText does not use the Styled Text Edit routines described in Inside 
Macintosh V To create a pane of styled text, use CStyleText. 

To make sure that the edit text pane responds to commands, you must place 
it in the chain of command. The best way to do this is to set the value of your 
document’s itsGopher instance variable to the edit pane. 

Because CEditText is based on the Macintosh TextEdit (TE) routines, it has 
some limitations. It’s designed to edit small amounts of text. The maximum 
number of characters you can store in a CEditText record is around 32,000, 
but you’ll notice performance degradation long before it gets that big. To 
create a pane to display more text (for a text editor, for example), create a 
subclass of CAbstractText, described on page 117. 


CAbstractText 

CStaticText 
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IViewRes 


Variables 

Variable Type 

macTE TEHandle 

spacingCmd longint 


alignCmd longint 


Description 

TextEdit record handle. 
Line spacing command 
number. 

Alignment command num¬ 
ber. 


Methods 

Construction and destruction methods 

procedure IEditText (anEnclosure: CView; 
aSupervisor: CBureaucrat; 
aWidth, aHeight: integer; 
aHEncl, aVEncl: integer; 
aHSizing, aVSizing: SizingOption; 
aLineWidth: integer); 

void IEditText (CView *anEnclosure, 

CBureaucrat *aSupervisor, 
short aWidth, short aHeight, 
short aHEncl, short aVEncl, 

SizingOption aHSizing, SizingOption aVSizing, 
short aLineWidth); 

Initialize an edit text pane. Most of the arguments to this method are identi¬ 
cal to the pane initialization. ALineWidth specifies how wide the lines 
should be. If it’s less than zero, the width is the same as the Macintosh TE 
record’s viewRect. 


Note 

The descriptions of the other arguments are in CPane on 
page 321. 


procedure IViewRes (rType:ResType; resID: integer; 
anEnclosure: CView; aSupervisor: CBureaucrat); 

void IViewRes (ResType rType, short resID, 

CView *anEnclosure, CBureaucrat *aSupervisor); 

Initialize edit text pane from a resource template. RType is the resource type 
for the CView subclass you want to initialize. Res ID is the resource ID of 
the resource. AnEnclosure and aSupervisor are the enclosure and su¬ 
pervisor of the pane. 

To initialize a text pane from a resource file, use a ' AbTx 1 resource. 
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MakeMacTE 


Free/Dispose 


DoClick 


PerformEditCommand 


TypeChar 


Draw 
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Note 

Earlier versions of the THINK Class Library used 1 St Tx 1 
resources to initialize static text and edit text panes. You 
should make sure that any old programs do not use 
1 StTx 1 . 


procedure MakeMacTE; 
void MakeMacTE (void); 

Create a TextEdit record and set macTE to it. 

procedure Free; 
void Dispose (void); 

Dispose the TextEdit record macTE. 

Mouse and Keystrokes methods 

procedure DoClick (hitPt: Point; 

modifierKeys: integer; when: longint); 

void DoClick (Point hitPt, short modifierKeys, 
long when); 

Handle a mouse down in an edit text pane. This method sends a Selec- 
tionChanged message after processing the click. 

Command methods 

procedure PerformEditCommand (theCommand: longint); 
void PerformEditCommand (long theCommand); 

Perform the standard cut, copy, paste, and clear commands on the text. The 
task classes call this method to undo an edit command. 

procedure TypeChar (theChar: char; 
theModifiers: integer); 

void TypeChar (char theChar, short theModifiers); 

Process a keystroke. This method does not need to set up for an Undo com¬ 
mand and should handle the key directly. The task classes call this method 
to undo key strokes. 

Display methods 

procedure Draw (var area: Rect); 
void Draw (Rect *area); 

Draw the text pane. 
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Scroll 


Activate 


Deactivate 


SetSelectlon 


CetSelection 


SetTextPtr 


GetTextHandle 


void Scroll (long hDelta, long vDelta, 

Boolean redraw); 

procedure Scroll (hDelta, vDelta: longint; 
redraw: Boolean); 

Scroll the text within the pane by hDelta characters and vDelta lines. 

procedure Activate; 
void Activate (void); 

Activate the text pane. This method enables the editing commands and ei¬ 
ther highlights the selection or shows the text insertion caret. 

procedure Deactivate; 
void Deactivate (void); 

Deactivate the text pane. This method disables the editing commands and 
either unhighlights the selection or hides the text insertion caret. 

procedure SetSelection (selStart, selEnd: long; 
fRedraw: Boolean); 

void SetSelection (long selStart, long selEnd, 

Boolean fRedraw); 

Set the selection to the range corresponding to character positions 
selStart through selEnd. 

procedure GetSelection (var selStart, selEnd: 
longint); 

void GetSelection (long *selStart, long *selEnd); 
Return the start and end of the current selection. 

Text specification methods 

procedure SetTextPtr (textPtr: Ptr; 
numChars: longint); 

void SetTextPtr (Ptr textPtr, long numChars); 

Use the first numChars characters that textPtr points to as the text for 
this abstract text object. This method makes a copy of the text. 

function GetTextHandle: CharsHandle; 

CharsHandle GetTextHandle (void); 

Return a handle to the text of the text. This method returns a handle to the 
actual text, not to a copy of the text. 


272 Object-Oriented Programming 



Methods 


CopyTextRange 


InsertT extPtr 


Checklnsertion 


SetFontNumber 


SetFontStyle 


SetFontSize 


SetTextMode 


--♦ 

function CopyTextRange (start, end: long): Handle; 
Handle CopyTextRange (long start, long end) ; 

Return a copy of the range of text specified by start and end. 

procedure InsertTextPtr (text: Ptr; length: longint; 
fRedraw: Boolean); 

void InsertTextPtr (Ptr text, long length. 

Boolean fRedraw); 

Insert a copy of the given text and length at the start of the current selection. 
If fRedraw is TRUE, redraw the pane at the next update event. 

procedure Checklnsertion (insertLen: longint; 
useSelection: Boolean); 

void Checklnsertion (long insertLen, 

Boolean useSelection); 

Check whether an insertion of insertLen characters would exceed TextE¬ 
dit’s capacity. If useSelection is TRUE, this method deducts the size of 
the selection from the total lenght. If the insertion would fail, this method 
calls Failure. 

Text characteristics methods 

procedure SetFontNumber (aFontNumber: integer); 
void SetFontNumber (short aFontNumber); 

Set the font for this text pane by font number. 

procedure SetFontStyle (aStyle: Style); 
void SetFontStyle (short aStyle); 

Toggle the font style for this text pane. AStyle may be one of: bold, 
italic, underline, outline, shadow, condense, or extend 

procedure SetFontSize (aSize: integer); 
void SetFontSize (short aSize); 

Set the font size for this text pane to the specified size. 

procedure SetTextMode (aMode: integer); 
void SetTextMode (short aMode); 

Set the text mode for this text pane to the specified mode. AMode can be one 
of srcOr, srcXor, or srcBic. 
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SetAlignCmd 


GetANgnCmd 


SetAlignment 


SetSpacingCmd 


GetSpacingCmd 


GetTEFontlnfo 


GetHeight 


GetCharOffset 


procedure SetAlignCmd (anAlignCmd: long); 
void SetAlignCmd (long anAlignCmd); 

Set the text alignment for this text pane. This method uses the THINK Class 
Library’s names for the alignment choices: cmdAlignLeft, 
cmdAlignRight, or cmdAlignCenter. 

function GetAlignCmd: longint; 
long GetAlignCmd (void); 

Return the current alignment for this text pane. It can be one of 
cmdAlignLeft, cmdAlignRight, cmdAlignCenter, or cmdNull. 

procedure SetAlignment (anAlignment: long); 
void SetAlignment (long anAlignment); 

Set the text alignment for this text pane. This method uses TextEdit’s names 
for the alignment choices: teFlushDef ault, teFlushLef t, teCenter, 
or teFlushRight. 

procedure SetSpacingCmd (aSpacingCmd: longint); 
void SetSpacingCmd (long aSpacingCmd); 

Set the space between lines of text. ASpacingCmd can be one of 
cmdSingleSpace, cmdlHalf Space, or cmdDoubleSpace. 

function GetSpacingCmd: longint; 
long GetSpacingCmd (void); 

Return the space between lines of text. It can be one of cmdSingleSpace, 
cmdlHalf Space, or cmdDoubleSpace. 

procedure GetTEFontlnfo (var macFontlnfo: Fontlnfo); 
void GetTEFontlnfo (Fontlnfo *macFontInfo); 

Return a QuickDraw Fontlnfo record for the font that this text pane uses. 

function GetHeight (startLine endLine: longint): 
longint; 

long GetHeight (long startLine, long endLine); 

Return the total height in pixels of the indicated lines of text. 

function GetCharOffset (aPt: LongPt): longint; 
long GetCharOffset (LongPt *aPt); 

Return the character position nearest the coordinate aPt. APt must be in 
frame coordinates. 
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CetCharPoint 


CetCharStyle 


GetTextStyle 


ResizeFrame 


CalcTERects 


AdjustBounds 


procedure GetCharPoint (offset: long; 
var aPt: LongPt); 

void GetCharPoint( long offset, LongPt *aPt) ; 

Return the coordinate of the character position offset. APt is in frame co¬ 
ordinates. 

procedure GetCharStyle (charOffset: long; 
var theStyle: TextStyle); 

void GetCharStyle (long charOffset, 

TextStyle *theStyle); 

Return style information for the character at position charOffset. 

procedure GetTextStyle (var whichAttributes: integer; 
var aStyle: TextStyle); 

void GetTextStyle (short *whichAttributes, 

TextStyle *aStyle); 

Return current style information for this text pane. WhichAttributes is a 
flag that indicates which text attributes to report on. The attributes flags and 
TextStyle record are described in Inside Macintosh VI, Chapter 15, 
“TextEdit” 

Calibrating methods 

procedure ResizeFrame (delta: Rect); 
void ResizeFrame (Rect *delta); 

Resize the static text’s frame when the size of its pane changes. The delta 
rectangle specifies how each side changes. Positive values mean down and 
to the right. Negative values mean up and to the left. 

procedure CalcTERects; 
void CalcTERects (void); 

Determine the destination and view rectangles for this text pane’s TextEdit 
record. 

procedure AdjustBounds; 
void AdjustBounds (void); 

Adjust the bounds of a this text pane to match its TextEdit record. When you 
do something that could change the line width or the number of lines, send 
this message. 
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♦- 

FindLine 


GetLength 


GetNumLines 


AboutToPrlnt 


PrintPage 


DonePrinting 


Dawdle 


function FindLine (charPos: longint): longint; 
short FindLine (long charPos); 

Return the line number containing the specified character position. Both line 
and character numbering start at zero. If the character position is before the 
start of the text (a negative number), this method returns zero. If the charac¬ 
ter position is beyond the end of the text, this method return the number of 
the last line. 

function GetLength: longint; 
long GetLength (void); 

Return the length in bytes of this text pane’s text buffer. 

function GetNumLines: longint 
long GetNumLines (void); 

Return the total number of lines in this text pane’s text buffer. 

Printing methods 

procedure AboutToPrint (var firstPage, lastPage: 
integer); 

void AboutToPrint (short *firstPage, short *lastPage); 

The specified range of pages is about to be printed. This method deactivates 
the text pane to unhighlight the current selection. 

procedure PrintPage (pageNum: integer; 
pageWidth, pageHeight: integer; 
aPrinter: CPrinter); 

void PrintPage (short pageNum, short pageWidth, 
short pageHeight, CPrinter *aPrinter); 

Print the specified page. 

procedure DonePrinting; 
void DonePrinting (void); 

Printing is over. This method re-highlights the current selection if the edit 
pane is active. 

Cursor methods 

procedure Dawdle (var maxSleep: longint); 
void Dawdle (long *maxSleep); 

This method flashes the insertion point when the edit text pane is active. 
This method sets maxSleep to the value of GetCaretTime, which is the 
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rate at which the insertion point blinks. Setting this value ensures that 
WaitNextEvent will generate a null event at least that often. 


Note 

To learn more about “sleep time,” see the description of the 
Dawdle message in CBureaucrat page 190. 
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Restore 


CEnvironment t 

33 


Introduction 

CEnvironment maintains a drawing environment for any pane. 

Heritage 

Superclass CObject 

Subclasses CTextEnvironment 

Using CEnvironment 

Every pane has an itsEnvironment instance variable. If this variable 
points to an object of this class, the Prepare method sends it a Restore 
message to set up the QuickDraw drawing environment for the pane. 

You can use this class to make sure that the drawing environment is set up 
correctly. Or you might want to change the drawing environment according 
to some saved settings. 

Variables 

This class has no instance variables. 

Methods 

procedure Restore; 
void Restore (void); 

Restore the drawing environment in the current port. The default method 
just calls the QuickDraw routine PenNormal. 


Object-Oriented Programming 279 



33 CEnvironment 


♦ 


280 Object-Oriented Programming 



CError # 
34 


Introduction 

CError is an error-handling class. You can use the global error handler to re¬ 
port errors. 


Note 

This class is included for compatibility with earlier versions 
of the THINK Class Library. New programs that you write 
with the THINK Class Library should use the exception 
handling mechanism described on page 101. 


Heritage 

Superclass CObject 

Subclasses None 

Using CError 

The application initialization method I Application creates an instance of 
CError and stores it in the global variable gError. Several objects in the 
THINK Class Library use the global error handler to post error messages. The 
default error handler reports messages and gives you a chance to quit or to 
proceed with the application. Create a subclass of this method to implement 
more sophisticated error recovery. 

Variables 

Global variable 

Variable Type Description 

gError CError Global error handler. 

Instance variables 

This class has no instance variables. 
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SevereMacError 


CheckOSError 


PostAlert 


MissingResources 


GrowZoneFunc 


Methods 

Error reporting methods 

procedure SevereMacError (macErr: OSErr); 
void SevereMacError (OSErr macErr); 

Report an operating system error in a Stop Alert that gives you a chance to 
quit the application or jump to the beginning of the event loop. This method 
looks for an Estr resource with the same ID as an operating system error. If 
it doesn’t find one, it uses the default string (S TR 200). If you press the Quit 
button, this method sends a Quit message to the application. If you press 
the Proceed button, this method sends the application a 
JumpToEventLoop message. 

function CheckOSError (macErr: OSErr): Boolean; 

Boolean CheckOSError (OSErr macErr); 

Check for a Macintosh operating system error. Return TRUE if everything is 
OK, FALSE otherwise. If macErr is an error, this method displays a Stop 
Alert. This method looks for an Estr resource with the same ID as the oper¬ 
ating system error. If it can’t find one, it uses a default string. 

procedure PostAlert (STRid: integer; index: integer); 
void PostAlert (short STRid, short index); 

Post a general alert and return. STRid is the resource ID of a STR# re¬ 
source. Index is the index into the STR# resource. The string is displayed 
in a generic alert box. 

procedure MissingResources; 
void MissingResources (void); 

Post an alert announcing that the application can’t find its resources, and exit 
the application. The alert suggests that your project doesn’t have an associat¬ 
ed resource file. The alert can’t be in a resource, since this method is called 
only if the resource file is unavailable. 

Functions 

Note that these are functions and procedures, not methods. 

function GrowZoneFunc (bytesNeeded: Size): longint; 
pascal long GrowZoneFunc (Size bytesNeeded); 

The application method InitMemory installs this function as the applica¬ 
tion’s GrowZone function which is called in low memory conditions. This 
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Class resources 


CheckResource 


CheckAllocation 


- ♦ 


function sends a GrowMemory message to the application. See CApplication 
on page 137. 

procedure CheckResource (r: Handle); 
void CheckResource (Handle r); 

If the handle h is NIL, this procedure sends the message 
SevereMacError (resNotFound) to the global gError: Call this func¬ 
tion after trying to retrieve a resource. 


procedure CheckAllocation (p: Ptr); 
void CheckAllocation (void *p); 

If p is NIL, the procedure calls SevereMacError (MemError) to report a 
severe memory error. Call this function after trying to allocate memory. 


Class resources 

Resource 

ALRT/DITL 128 

ALRT/DITL 200 
ALRT/DITL 300 

STR 300 

Estr resources 


Description 

Generic alert box. Contains ~0 for use 
with ParamText. 

Alert box for a SevereError 
Alert box for a Macintosh operating sys¬ 
tem error. 

String that reports a severe Macintosh sys¬ 
tem error 

An Estr resource has the same format as 
a STR resource. The SevereMacError 
method looks for an Estr resource with 
the same ID as an operating system error. 
For instance, Estr -42 might read 
“Too many files open.” 
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CFile 

35 


Introduction 

CFile is an abstract class for implementing classes that deal with disk files. 

Heritage 

Superclass CObject 

Subclasses CDataFile 

CResFile 

Using CFile 

CFile is an abstract class for dealing with Macintosh disk files. Most of the 
time you’ll use the CDataFile subclass to work with regular data files. 

Before you open a file, you must specify it. Specifying means identifying it to 
the Macintosh file manager. This class gives you three ways to specify a file 
depending on the type of information you can provide. The most common 
specification method, SFSpecify, lets you use an SFReply record from 
the standard file dialogs to identify a file. 

Some CFile methods use the THINK Class Library’s exception handling li¬ 
brary if something goes wrong in a file operation. For more information on 
exception handling, see Chapter 8, “Exception Handling. 


Note 

This version of CFile handles errors differently than the ver¬ 
sion included with earlier versions of the THINK Class Li¬ 
brary. The old version is now named OFile and is in the 
Compatibility Classes folder. 


Object-Oriented Programming 285 




35 CFile 


♦--- 

Description 

File name 

Volume containing the file 
Directory within the vol¬ 
ume 

Methods 

Construction and destruction methods 
IFHe procedure IFile; 

void IFile (void); 

Initialize the file object. 



Free/Dispose procedure Free; 

void Dispose (void); 

Close and dispose of the file object. 

Specifying methods 

Specify procedure Specify (aName: Str63; aVolNum: integer); 

void Specify (Str63 aName, short aVolNum) ; 

Specify a file by its name and volume reference number. Use this method to 
specify files on MFS volumes. 


SpecifyHFS procedure SpecifyHFS (aName: Str63; aVolNum: integer; 

aDirlD: longint); 

void SpecifyHFS (Str63 aName, short aVolNum, 
long aDirlD); 

Specify a file by its name, volume number, and directory ID. If the specifica¬ 
tion is for an alias, this method resolves it. 


SpecifyFSSpec procedure SpecifyFSSpec (aFileSpec: FSSpec); 

void SpecifyFSSpec (const FSSpec *aFileSpec) 

Specify the File using a File Manager FSSpec record. If the specification is 
for an alias, this method resolves it. 


SFSpedfy procedure SFSpecify (macSFReply: SFReplyPtr); 

void SFSpecify (SFReply *macSFReply); 

Specify a file from the information in a macSFReply record. If the specifica¬ 
tion is for an alias, this method resolves it. Use this method to specify a file 
that the user chose through a standard file dialog. 
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Open 


Close 


GetName 


GetFSSpec 


ExistsOnDisk 


GetMacFilelnfo 


Create New 


Methods 

-♦ 

procedure ResolveFileAlias; 
void ResolveFileAlias (void) 

If the file specification is an alias, resolve it. 

Open and close methods 

procedure Open (permission: SignedByte); 
void Open (SignedByte permission); 

Open the file with the specified permission. This method does nothing. Sub¬ 
classes must override this method. For an example of how to write an Open 
method, see CDataFile and other descendants of this class. 

procedure Close; 
void Close (void); 

Close this file. This method does nothing. Subclasses must override this 
method. 

Accessing methods 

procedure GetName (var theName: Str63); 
void GetName (Str63 theName); 

Get the name of the file. 

procedure GetFSSpec (var aFileSpec: FSSpec); 
void GetFSSpec (FSSpec *aFileSpec) 

Get an FSSpec record for this file. 

function ExistsOnDisk: Boolean; 

Boolean ExistsOnDisk (void); 

Returns TRUE if there’s an existing file that matches the current specification. 

procedure GetMacFilelnfo (var filelnfo: FInfo) 
void GetMacFilelnfo (FInfo *filelnfo); 

Return the Finder information for this file. The information includes the file’s 
type, creator, and icon position. 

Filing methods 

procedure CreateNew (creator, fType: OSType); 
void CreateNew (OSType creator, OSType fType); 

Create new file with the specified creator and file type. This method uses the 
name and volume information you set up with one of the specification 
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ThrowOut 


ChangeName 


methods. You can use the application signature in gSignature for the cre¬ 
ator. 

procedure ThrowOut; 
void ThrowOut (void); 

Close the file and delete it. 

procedure ChangeName (newName: Str255); 
void ChangeName (Str63 newName); 

Give this file a new name. 
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36 


Introduction 

CFWDesktop is a subclass of CDesktop that supports floating windows. 

Heritage 

Superclass CDesktop 

Subclasses None 

Using CFWDesktop 

CFWDesktop is a subclass of CDesktop that supports floating windows. In 
general, your application shouldn’t need to send messages to the desktop. 

If you use CFWDesktop, be sure to override MakeDesktop to create a float¬ 
ing window desktop and store the object in gDesktop. 

This is how you do it in Pascal: 

procedure CMyApp.MakeDesktop; 
begin 

new(CFWDesktop(gDesktop)); 

CFWDesktop(gDesktop).IFWDesktop(SELF); 
end; 

And this is how you do it in C: 

void CMyApp::MakeDesktop(void) 

{ 

gDesktop = new(CFWDesktop); 

((CFWDesktop*)gDesktop)->IFWDesktop(this); 

} 


To make a floating window, just pass TRUE as the aFloat ing parameter to 
IWindow, CWindow’s intialization method. 
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IFWDesktop 


Free/Dispose 


Show 


Hide 


Activate 


Deactivate 


Variables 

Variable Type Desktop 

itsFloats CList List of floating windows 

topFloat CWindow Topmost floating window 

Methods 

Construction and destruction methods 

procedure IFWDesktop (aSupervisor: CBureaucrat); 
void IFWDesktop (CBureaucrat *aSupervisor); 

Initialize the desktop. This method calls CDesktop’s initialization method 
and creates the list of floating window.. 

procedure Free; 
void Dispose (void); 

Dispose of the desktop and send this message to all of the desktop’s win¬ 
dows. 

Appearance methods 

procedure Show; 
void Show (void); 

Makes a desktop visible by showing all of its windows. This method sends a 
Show message to all of the desktop’s windows and floating windows. 

procedure Hide; 
void Hide (void); 

Hide a desktop by hiding all of its windows. This method sends a Hide mes¬ 
sage to all of the desktop’s windows and floating windows. 

procedure Activate; 
void Activate (void); 

Activate the desktop by activating all the windows. This method sends an 
Activate message to the desktop’s top window and to all of the floating 
windows. 

procedure Deactivate; 
void Deactivate (void); 

Deactivate a desktop by deactivating all the windows. This method sends a 
Deactivate message to the desktop’s top window and to all of the float¬ 
ing windows. 
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AdjustCursor 


AddWind 


RemoveWind 


Select Wind 


ShowWInd 


HideWind 


-♦ 

Mouse methods 

procedure AdjustCursor (where: Point; 
mouseRgn: RgnHandle); 

void AdjustCursor (Point where, RgnHandle mouseRgn); 

Adjust the cursor shape when the mouse is in an insignificant part of the 
desktop. The default method sets the cursor to an arrow. 

Window methods 

You do not have to use any of these methods yourself. Directors, objects that 
manage the interaction between windows and the desktop, take care of 
sending most of these messages. 

procedure AddWind (theWindow: CWindow); 
void AddWind (CWindow *theWindow); 

Add theWindow to the desktop’s window list. If the window is a floating 
window, add it to the beginning of the itsFloats list. 

procedure RemoveWind (theWindow: CWindow); 
void RemoveWind (CWindow *theWindow); 

Remove theWindow from the desktop’s window list. If the window is a 
floating window, remove it from the itsFloats list. 

procedure SelectWind (theWindow: CWindow); 
void SelectWind (CWindow *theWindow); 

Select theWindow and bring theWindow to the front. It the window is a 
floating window, bring it to the front of the it sFloats list and mark it as 
the topFloat window. 

procedure ShowWind (theWindow: CWindow); 
void ShowWind (CWindow *theWindow); 

Make theWindow visible on the desktop. 

procedure HideWind (theWindow: CWindow); 
void HideWind (CWindow *theWindow); 

Hide theWindow. 
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Drag Wind 


CalTopFloat 


Cleanup 


procedure DragWind (theWindow: CWindow; 
macEvent: EventRecord); 

void DragWind (CWindow *theWindow, 

EventRecord *macEvent); 

Drag theWindow on the desktop. This method does not use DragWindow 
Toolbox routine. 

procedure CalcTopFloat; 
void CalcTopFloat (void); 

Set top FI oat to the first visible floating window. Send this message to the 
desktop if you hide or remove a floating window. 

Cleanup method 

procedure Cleanup; 

This method is for THINK Pascal. When you’re running in the THINK Pascal 
environment, all the windows share the same space. As you debug your pro¬ 
gram and open source windows and debugging windows, the window or¬ 
der changes. When you resume your program, THINK Pascal will move your 
application’s active window to the front, but it doesn’t know about floating 
windows. This method moves all of THINK Pascal’s windows to the back, 
and cleans up your application windows so the floating windows float and 
the application windows are in the right order. 
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37 


Introduction 

CGridSelector is an abstract class for drawing a pane with several items ar¬ 
ranged in a table. 

Heritage 

Superclass CSelector 

Subclasses CCharGrid 

CPatternGrid 

Using CGridSelector 

CGridSelector is a descendant of CSelector that lets you display items in a ta¬ 
ble. To use CGridSelector, all you have to do in your subclass is override the 
Drawltem method. CGridSelector takes care of everything else. 

The THINK Class Library includes two subclasses of CGridSelector. CPattern¬ 
Grid displays a pattern palette. CCharGrid displays a set of characters. You 
can use CCharGrid with a special font to display tool palettes. 

Items in a grid are numbered from 1, row first. 

Variables 


Variable 

Type 

Description 

rows 

integer 

The number of rows in the 
grid. 

columns 

integer 

The number of columns in 
the grid. 

boxWidth 

integer 

The width in pixels of 
each box. 

boxHeight 

integer 

The height in pixels of 
each box. 

gridOn 

Boolean 

True if the grid lines 
should be drawn. 
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IGridSelector 


See the description of CSe- 
lector's DoClick method on 
page 395to learn how se¬ 
lectors generate command 
numbers. 


Draw 


Methods 

Construction methods 

procedure IGridSelector (anEnclosure: CView; 
aSupervisor: CBureaucrat; 
aWidth, aHeight: integer; 
aHEncl, aVEncl: integer; 
aHSizing, aVSizing: SizingOption; 
aSelection, aComraandBase: integer 

aRows, aColumns, aBoxWidth, aBoxHeight: integer); 

void IGridSelector (CView *anEnclosure, 

CBureaucrat *aSupervisor, 
short aWidth, short aHeight, 
short aHEncl, short aVEncl, 

SizingOption aHSizing, SizingOption aVSizing, 
short aSelection, short aCommandBase 
short aRows, short aColumns, 
short aBoxWidth, short aBoxHeight); 

Initialize a selector. The first eight arguments to this routine are identical to 
the ones for IPane. 

ASelection is the initial item to select. ACommandBase is the base value 
for converting the selected item into a command number. ARows and 
aColumns determine how many boxes are in the gird. ABoxWidth and 
aBoxHeight determine the size of each box in pixels. Finally, IGridSe¬ 
lector sets the vertical and horizontal scales to the size of the boxes. 


Note 

The descriptions of the other arguments are in CPane on 
page 321. 


Drawing methods 

procedure Draw (var area: Rect); 
void Draw (Rect *area); 

Draws the grid selector. If gridOn is true, this method first draws the grid. 
Then it uses Drawltemto draw each box. Finally, it highlights the current 
selection. 

Since most of the work is done in the Drawltem method, you probably 
won’t need to override this method. 
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DrawGrid 


Drawl tern 


Hiliteltem 


Findltem 
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procedure DrawGrid; 
void DrawGrid (void); 

Draw the grid lines between items. The Draw method calls DrawGrid if 
gridOn is TRUE. 

procedure Drawltem (theltem: integer; 
theBox: Rect); 

void Drawltem (short theltem, Rect *theBox); 

Draw the item. Theltem is the number of the item to draw, and theBox is 
the rectangle to draw it in. Your subclass must override this method. 

Accessing methods 

procedure Hiliteltem (theltem: integer; 
state: HiliteState); 

void Hiliteltem (short theltem, HiliteState state); 

Hilight the specified item. Hiliteltem can take on of three values for the 
state parameter: 

Hilite state value Behavior 

hiliteOFF Invert the item’s box. 

hiliteON Invert the item’s box. 

hiliteDYNAMIC Flash the edges of the item’s box. 

If you want to higlight an item differently, you can override this method. 

function Findltem (hitPt: Point): integer; 
short Findltem (Point hitPt); 

Determine which item corresponds to a mouse down at a specified point. If 
the hitPt isn’t in the grid, Findltem returns zero. Grid selector items are 
numbered from 1, row first like this: 


1 

2 

3 

4 

5 

6 

7 

8 

9 


Figure 37-1 Item numbering in grid selectors 
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FindltemBox 


SetCridOn 


procedure FindltemBox (theltem: integer; 
var theBox: Rect); 

short FindltemBox (short theltem, Rect *theBox); 

Return the box that corresponds to theltem. Hiliteltem uses this meth¬ 
od to figure our what box to highlight. 

procedure SetGridOn (aGridOn: Boolean); 
void SetGridOn (Boolean aGridOn); 

Sets the instance variable gridOn to aGridOn. If gridOn is true, the Draw 
method calls DrawGrid to draw grid lines between items. 
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Introduction 

CList implements an ordered list of objects. 

Heritage 

Superclass CCluster 

Subclasses None 

Using CList 

Use an object of class CList when you need to maintain an ordered list of ob¬ 
jects. Several of the objects in the THINK Class Library use CList to maintain 
lists. You can use the iteration methods inherited from CCluster to apply 
functions to each item in a list. Every object in a list has an index. Index val¬ 
ues begin at 1. 

Variables 

This class has no instance variables. 

Methods 

For methods that insert new objects before or after existing objects, be sure 
that the existing object is actually in the list. If you don’t, strange things may 
happen. 

Construction methods 

CList inherits the Free (in THINK Pascal) or Dispose (in THINK C) meth¬ 
od from CCluster. 

IList procedure IList; 

void IList (void); 

Initialize the list. 
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Append 


Prepend 


InsertAfter 


InsertAt 


BringFront 


SendBack 


Movellp 


MoveDown 


Insertion and deletion methods 

procedure Append (theObject: CObject); 
void Append (CObject *theObject); 

Add theOb ject to the end of the list. 

procedure Prepend (theObject: CObject); 
void Prepend (CObject *theObject); 

Add theOb ject to the beginning of the list. 

procedure InsertAfter (theObject: CObject; 
afterObject: CObject); 

void InsertAfter (CObject *theObject, 

CObject *afterObject); 

Insert the theOb ject after the object specified by afterObject. 

procedure InsertAt (theObject: CObject; 
index: longint); 

void InsertAt (CObject *theObject, long index); 

Make theOb ject be the indexth object in the list. All subsequent objects 
move down one position 

Ordering methods 

procedure BringFront (theObject: CObject); 
void BringFront (CObject *theObject); 

Make theObject be the first object in the list. 

procedure SendBack (theObject: CObject); 
void SendBack (CObject *theObject); 

Make theObject be the last object in the list. 

procedure MoveUp (theObject: CObject); 
void MoveUp (CObject *theObject); 

Move theObject up one slot toward the front of the list. The object that 
was before it in the list moves down one slot. 

procedure MoveDown (theObject: CObject); 
void MoveDown (CObject *theObject); 

Move theObject down one slot toward the end of the list. The object that 
was after it in the list moves up one slot. 
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MoveToIndex 


Firstltem 


Lastltem 


Nthltem 


Findlndex 


FirstSuccess 


FirstSuccessI 


--- ♦ 

procedure MoveToIndex (theObject: CObject; 
index: longint); 

void MoveToIndex (CObject *theObject, long index); 

Move theObject to the indexth position in the list. If theObject moves 
back in the list, the items between its original position and its new position 
move up one slot. If theObject moves forward in the list, the items be¬ 
tween its new position and its original position move down one slot. 

Membership methods 

function Firstltem: CObject; 

CObject* Firstltem (void); 

Return the first item in the list. 

function Lastltem: CObject; 

CObject* Lastltem (void); 

Return the last item in the list. 

function Nthltem (n: longint): CObject; 

CObject* Nthltem (long n); 

Return the nth item in the list. 

function Findlndex (theObject: CObject): longint; 
long Findlndex (CObject *theObject); 

Return the index of the object. Indexes begin at 1. If the item is not in the list, 
this method returns 0. 

function FirstSuccess (function testFunc(theObject: 
CObject): Boolean): CObject; 

CObject* FirstSuccess (TestFunc testFunc); 

Return the first item that causes the testFunc function to return TRUE. 

In THINK C, testFunc must be declared like this: 

Boolean MyTestFunc (CObject *theObject); 

function FirstSuccessI (function testFunc (theObject: 
CObject; theParam: Ptr) : Boolean; param: Ptr) : 
CObject; 

CObject* FirstSuccessI (TestFuncl testFunc, 
long param); 

Return the first item that causes the testFunc function to return TRUE. 
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LastSuccess 


LastSuccessI 


In THINK C, testFunc must be declared like this: 

Boolean MyTestFunc (CObject *theObject, 
long param); 

function LastSuccess (function testFunc(theObject: 
CObject): Boolean): CObject; 

CObject* LastSuccess (TestFunc testFunc); 

Return the last item in the list that causes the testFunc function to return 
TRUE. 

In THINK C, testFunc must be declared like this: 

Boolean MyTestFunc (CObject *theObject); 

function LastSuccessI (function testFunc(theObject: 
CObject; theParam: Ptr) : Boolean; param: Ptr) : 
CObject; 

CObject* LastSuccessI (TestFuncl testFunc, 
long param); 

Return the last item in the list that causes the testFunc function to return 
TRUE. 

In THINK C, testFunc must be declared like this: 

Boolean MyTestFunc (CObject *theObject, 
long param); 
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39 


Introduction 

CMBarChore is a chore that works with CBartender to redraw the menu bar. 

Heritage 

Superclass CChore 

Subclasses None 

Using CMBarChore 

The CBartender class uses a CMBarChore to redraw the menu bar after delet¬ 
ing menus from the menu bar. Your application should not need to use this 
class. 

The CBartender’s DeleteFromBar method creates a CMBarChore and as¬ 
signs it as an urgent chore, so the menu bar gets redrawn the next time 
through the event loop. 

Variables 

This class has no instance variables. 

Methods 

Perform procedure Perform (var maxSleep: Longint); 

void Perform (long *maxSleep); 

This method calls the Toolbox routine DrawMenuBar to redraw the menu 
bar. 
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40 


Introduction 

CMenuDefProc is an abstract class that gives you an object-oriented inter¬ 
face for Macintosh menu definition procedures (MDEFs). The description of 
this class assumes that you’re familiar with the Macintosh Menu Manager in 
general and with MDEFs in particular. If you need to learn more, see Inside 
Macintosh /, Chapter 11, “The Menu Manager” and Inside Macintosh V, 
Chapter 13, “The Menu Manager.” 

Heritage 

Superclass CObject 

Subclasses CPaneMDEF 

Using CMenuDefProc 

CMenuDefProc lets you write object-oriented menu definition functions. To 
write an MDEF object, you need to create a subclass of CMenuDefProc or 
use one of the ones provided in the THINK Class Library. 

CMenuDefProc uses a stub MDEF that contains a jump to a generic menu 
definition procedure and a reference to an MDEF object. The Menu Manager 
calls the generic menu definition procedure which dispatches messages to 
your MDEF object. 

Creating the stub MDEF 

The stub MDEF is a 10-byte data structure that looks like this in Pascal: 

GenericMDEFRec = record 

JMPinstruction: integer; 
defProc: ProcPtr; 
itsMenuDefProc: CMenuDefProc; 
end; 
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And in C it looks like this: 

typedef struct GenericMDEFRec { 
short JMPinstruction; 

VoidFunc defProc; 

CMenuDefProc* itsMenuDefProc; 

}; 


To create the MDEF, use your favorite resource editor or resource compiler to 
create a 10-byte resource that contains these hex values: 


4EF9 0000 0000 0000 0000 


When you create the menu 
that uses your MDEF, be 
sure to specify the MDEF 
ID. Otherwise, the Menu 
Manager uses the default 
MDEF. 


Apple reserves IDs 0 to 127 for definition procedures and recommends that 
you number your MDEF in the range 128 to 4095. In the THINK Class Library, 
the convention is to give your MDEF the same ID as the menu that you’ll be 
using it with. 

Writing the CMenuDefProc subclass 

Your object-oriented MDEF must handles all the messages that a regular 
MDEF handles. That means that your subclass needs to override all the meth¬ 
ods of CMenuDefProc: 


Initialization DrawMenu Choose Item 

SizeMenu PlacePopup 

Your subclass can define instance variables to hold whatever information 
your menu needs to do its work. Your initialization method should allocate 
memory for the instance variables if necessary. Your subclass must call 
IMenuDefProc to setup the stub MDEF resource. 

If you want to use your MDEF for more than one menu, be careful how you 
use instance variables. If the instance variables of the MDEF control the state 
of the menu being displayed, you’ll only be able to use it for one menu. 

For example, the CPaneMDEF subclass of this class keeps two instance vari¬ 
ables to refer to the pane being displayed as a menu and to the tear-off 
menu. If you were to use the same MDEF based on CPaneMDEF for two 
menus, both menus would display the same pane. 

Using your CMenuDefProc subclass 

The most important thing to keep in mind about using a descendant of 
CMenuDefProc is that you need to intialize it before the Menu Manager 
loads the menu associated with it. If you don’t, your application will crash. 
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The description for Ceneric- 
MDEF is near the end of 
this chapter on page 308 


♦ 


The reason that it’s important to initialize the custom MDEF object before 
CApplication’s SetUpMenus or CBartender’s AddMenu has to do with the 
way the Menu Manager works and the way IMenuDef Proc does its job. 

IMenuDef Proc loads the MDEF and sets up the fields so def Proc points 
to a function called GenericMDEF, and the itsMenuDef Proc points to 
the current object. GenericMDEF is the “real” menu definition procedure 
that dispatches Menu Manager messages to your MDEF object. 

As it’s loading the menu, the Toolbox routine GetMenu loads the MDEF and 
sends it an mSizeMsg to find out how big the menu is. If you haven’t initial¬ 
ized the MDEF, this call to menu definition procedure will jump to random 
memory, and your program will crash. 

Examples of MDEF objects 

If you’re including the menu in your application’s MBAR resource, override 
CApplication’s SetUpMenus method to create the MDEF object and initial¬ 
ize it. Then call CApplication’s SetUpMenus method. Chances are that 
you’re overriding this method anyway to load resource-based menus like 
the Font menu and to set up the dimming and checking options for your 
menus. 

This is what your SetUpMenus method should look like in Pascal: 

procedure CMyApp.SetUpMenus; 
var 

theMDEF: CMyCustomMDEF; 
begin 

new(theMDEF); 

theMDEF.IMyCustomMDEF(CustomID); 
inherited SetUpMenus; 

{ load font menu, set check & dim options } 
end; 

In C, it should look like this: 

void CMyApp::SetUpMenus (void) 

{ 

CMyCustomMDEF theMDEF; 

theMDEF = new(CMyCustomMDEF); 
theMDEF->IMyCustomMDEF(CustomID); 
inherited::SetUpMenus(); 

/* load font menu, set check & dim options */ 

} 
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Your initialization method (iMyCustomMDEF in this example) must call 
CMenuDefProc’s IMenuDef Proc. 

If you’re using CBartender’s AddMenu method to add the menu to the menu 
bar, you need to create and initialize the MDEF object before you call 
AddMenu. The next example shows a method that creates a tool menu that 
uses a custom MDEF and adds it to the end of the menu bar. Note that the ex¬ 
ample uses the TCL convention of giving the menu and MDEF the same ID. 

This is what the method looks like in Pascal: 

procedure CPaintPane.AddToolMenu; 
var 

theToolMDEF: CToolMDEF; 
begin 

new(theToolMDEF); 

theToolMDEF.IToolMDEF(ToolMENUID); 
gBartender.AddMenu(ToolMENUID, TRUE, 0); 
end; 

In it looks like this: 

void CPaintPane::AddToolMenu(void) 

{ 

CToolMDEF theToolMDEF; 

theToolMDEF = new(CToolMDEF); 
theToolMDEF->IToolMDEF(ToolMENUID); 
gBartender->AddMenu(ToolMENUID, TRUE, 0); 

} 

Variables 

This class has no instance variables. 

Methods 

Except for the initialization method, all of CMenuDefProc’s methods handle 
a Menu Manager message to a menu definition procedure. The descriptions 
given here of what your subclass should do are fairly complete, but for de¬ 
tails, be sure to consult Inside Macintosh /, Chapter 11, “The Menu Manager” 
and Inside Macintosh V t Chapter 13, “The Menu Manager.” 
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IMenuDefProc 


DrawMenu 


Chooseltem 


SizeMenu 


PlacePopUp 


procedure IMenuDefProc (MDEFid: Integer); 
void IMenuDefProc (short MDEFid); 

Initialize the object. This method loads the stub MDEF and stores the address 
of the generic MDEF function GenericMDEF in the defProc field. It stores 
the reference to this object in the itsMenuDef Proc field. 

procedure DrawMenu (macMenu: MenuHandle; 
menuRect: Rect); 

void DrawMenu (MenuHandle macMenu, Rect *menuRect); 

Draw the menu in response to a Menu Manager mDrawMsg. MenuRect is 
given in global coordinates, the current port is the Window Manager port, 
and the clipping region is set to menuRect. Your DrawMenu method 
should check whether the menu is enabled and draw it in gray if it’s not. 

procedure Chooseltem (macMenu: MenuHandle; 
menuRect: Rect; hitPt: Point; 
var whichltem: Integer); 

void Chooseltem(MenuHandle macMenu, Rect *menuRect, 
Point hitPt, short *whichltem); 

Choose an item in response to a Menu Manager mChooseMsg. Both hitPt 
and menuRect are in global coordinates, and whichltem is the last item 
chosen. Whichltem is initially 0. Your Chooseltem method should check 
that hitPt is within menuRect, and if it is, it should unhighlight which¬ 
ltem and highlight the new item (if it’s not the same as whichltem), then 
set whichltem to the new item. If hitPt isn’t in menuRect, you should 
unhighlight whichltem and set whichltem to 0. 

procedure SizeMenu (macMenu: MenuHandle); 
void SizeMenu (MenuHandle macMenu); 

Set the size of the menu in response to a Menu Manager mSizeMsg. Your 
method should store the height of the menu in macMenu’s menuWidth field 
and the height in the menuHeight field. Note that the menu manager sends 
this message to your menu soon after it has been loaded. See “Using your 
CMenuDefProc subclass” on page 304 for more details. 

procedure PlacePopUp (macMenu: MenuHandle; 
menuRect: Rect; hitPt: Point; 
var whichltem: integer); 

void PlacePopUp (MenuHandle macMenu, Rect *menuRect, 
Point hitPt, short *whichltem); 

Determine the rectangle for a pop-up menu in response to a Menu Manager 
mPopUpMsg. Whichltem contains the previously selected item, and 
hitPt contains the top left corner of the pop-up menu (hitPt. h contains 
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the top and hitPt. v contains the left). Your method should set menuRect 
to the rectangle the menu is displayed in. If the menu would scroll, set 
whichltem to the actual top item. Inside Macintosh V, Chapter 13, “The 
Menu Manager” contains additional informati on you should be aware of. 

Functions 

CMenuDefProc uses an auxiliary function, GenericMDEF, to convert mes¬ 
sages from the Menu Manager to object-oriented messages. In THINK C, this 
function is in GenericMDEF. c in the FW/Tearof f s folder, and in THINK 
Pascal it’s in GenericMDEF .p in the FW/Tearof fs folder. 

procedure GenericMDEF (theMesage: integer; 
macMenu: MenuHandle; 
menuRect: Rect; hitPt: Point; 
var whichltem: integer); 

pascal void GenericMDEF (short theMessage, 

MenuHandle macMenu, Rect *menuRect, 

Point hitPt, short *whichltem); 

As far as the Menu Manager is concerned, GenericMDEF is the “real” menu 
definition procedure. GenericMDEF. This routine dispatches messages to 
your object-oriented MDEF. 

Be aware that the GenericMDEF only handles the four standard Menu Man¬ 
ager messages. If you write an MDEF that responds to user messages (as de¬ 
scribed in Inside Macintosh V, Chapter 13, “The Menu Manager”), you will 
need to write your own version of GenericMDEF and write your initializa¬ 
tion method accordingly. 
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Introduction 

CMouseTask is an abstract class that implements mouse tracking. 

Heritage 

Superclass CTask 

Subclasses You must define a subclass of this class. 

Using CMouseTask 

CMouseTask is an abstract class that lets you implement undoable mouse-re¬ 
lated actions. For example, if you’re writing a drawing application, you want 
to make sure that you can undo anything that you move or draw. 

You don’t have to use this class to implement mouse-related actions. You 
can always track the mouse yourself in your pane’s DoClick method. If you 
do use CMouseTask to implement mouse actions, you don’t have to make 
them undoable. 

Defining a mouse task 

To implement a mouse tracking task, define a subclass of CMouseTask and 
override the KeepTracking and EndTracking methods. The 
KeepTracking method does whatever you want to happen while the 
mouse is down. The EndT racking method does whatever you want to 
happen when the mouse is released. 

For example, if you’re moving a rectangle from one place in a pane to anoth¬ 
er, the KeepTracking method might draw a gray outline that moves as 
you move the mouse. The EndT racking method would erase the rectan¬ 
gle from its old location and redraw it in the new location. 

If you want to make your mouse task undoable, you need to store enough 
information in the object to undo the effects of mouse tracking. You must 
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also override the Undo method (inherited from CTask) to use this informa¬ 
tion to undo the effects of the mouse task. 

Using the moving rectangle example again, your EndTracking method 
might keep the old location of the rectangle in an instance variable. The 
Undo method would erase the rectangle from its current location and re¬ 
draw it again in the old location. 

Using the mouse task 

You use mouse tasks in the DoClick method of a pane. Create an instance 
of your mouse task, initialize it, and pass it in a TrackMouse message to 
your pane. This is what part of your DoClick method might look like in 
THINK Pascal: 

var 

myMover: CShapeMover; 
begin 

new(myMover ); 

myMover.IShapeMover(UNDOMoverStr); 

TrackMouse(myMover, hitPt, pinRect); 
itsSupervisor.Notify(myMover); 

end 

And this is what part of your DoClick method might look like in THINK C: 
CShapeMover *myMover; 

myMover = new(CShapeMover); 
myMover->IShapeMover(UNDOMoverStr); 

this->TrackMoouse(myMover, hitPt, SpinRect); 
itsSupervisor->Notify(myMover); 

The TrackMouse method sends your mouse task a BeginTracking mes¬ 
sage to give you an opportunity to adjust the starting point. As long as the 
mouse button is down, TrackMouse repeatedly sends KeepTracking 
messages to your mouse task. When the mouse button is released, 
TrackMouse sends your mouse task an EndTracking message. 

The value you pass to your initialization method is the index of a string in 
the STR# 130 resource that describes your task. The document method 
UpdateUndo uses this string for the wording of the Undo command in the 
Edit menu. If your task is not undoable, you can use any value and ignore it. 
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IMouseTask 


BeginTracking 


KeepTracking 


EndTracking 


--- ♦ 

After you’ve tracked the mouse, you can send the task in a Notify message 
to the document. The document will store the task in the document’s 
lastTask instance variable. When you choose Undo from the Edit menu, 
the document sends an Undo message to the task to undo the effects of 
mouse tracking. 

Variables 

This class has no instance variables. 

Methods 

Construction and destruction methods 

procedure IMouseTask (aNamelndex: integer); 
void IMouseTask (short aNamelndex); 

Initialize a mouse tracking task. ANamelndex is the index for the undo/ 
redo string in the STR# 130 resource. 

Mouse tracking methods 

procedure BeginTracking (var startPt: LongPt); 
void BeginTracking (LongPt *startPt); 

Mouse tracking is starting. The document’s TrackMouse method sends this 
message at the beginning of mouse tracking. StartPt is the starting point 
(in local coordinates). If your mouse task subclass doesn’t alter the starting 
point, you don’t need to override this method. 

procedure KeepTracking (var currPt, prevPt, startPt: 
LongPt); 

void KeepTracking (LongPt *currPt, LongPt *prevPt, 
LongPt *startPt); 

Mouse tracking is under way. The document’s TrackMouse method sends 
this message repeatedly as long as the mouse button is down. CurrPt is the 
current mouse location. PrevPt is the previous mouse location. StartPt 
is a the original mouse location. Your mouse task subclass must override this 
method. 

procedure EndTracking (var currPt, prevPt, startPt: 
LongPt); 

void EndTracking (LongPt *currPt, LongPt *prevPt, 
LongPt *startPt); 

Mouse tracking is over. The document’s TrackMouse method sends this 
message when the mouse button is released. CurrPt is the current mouse 
location. PrevPt is the previous mouse location. StartPt is the original 
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mouse location. Your mouse task subclass must override this method. If 
your mouse task is undoable, you should store all the information you need 
to undo it in this method. 


Note 

If you’re implementing an undoable mouse task, you’ll 
need to override the Undo method as well. 


Class resources 

Resource Description 

STR# 130 List of strings that describe undoable 

tasks. For example, if you’re implement¬ 
ing a mouse task that moves graphic imag¬ 
es, the string for that task might be 
“move.” The item in the Edit menu would 
then read “Undo move” or “Redo move.” 


3 7 2 Object-Oriented Programming 



CObject j 
42 


Introduction 

CObject is the abstract root level class. It is the ancestor of all the classes in 
the THINK Class Library. 


Heritage 

Superclass None 

Subclasses CAppleEvent 

CBartender 

CBitMap 

CChore 

CCollaborator 

CDecorator 

CEnvironment 

CError 

CFile 

CMenuDefProc 

CPaneBorder 

CPrinter 

CSwitchboard 

CTask 


Using CObject 

Every class in the THINK Class Library is a descendant of this class. CObject 
is the only class with no superclass. If you need to create a new class that 
can’t be a subclass of any other class, make it a subclass of CObject. 

Variables 

This class has no instance variables. 

Methods 

All classes inherit these methods: 


Object-Oriented Programming 313 



42 CObject 


♦ 

Free/Dispose 

Clone/Copy 

Lock 

SubdassResponsibility 

GetClassName 


Creation and destruction 

procedure Free; 
void Dispose (void); 

Dispose of the memory an object occupies. If your subclass allocates memo¬ 
ry in its initialization method, be sure you release it in this method. 

function Clone: CObject; 

CObject *Copy (void); 

Make a copy of the object. Note that if a class has instance variables that 
point to a block of memory, only the reference is copied, not the contents of 
the block of memory. 

function Lock (fLock: Boolean): Boolean; 

Boolean Lock (Boolean fLock) 

When fLock is TRUE, make this object non-relocatable. When fLock is 
FALSE, make it relocatable. This method returns TRUE if the object was 
locked. 

procedure SubdassResponsibility; 
void SubdassResponsibility (void) ; 

In some cases, certain methods inherited from abstract classes must be over¬ 
ridden, or the subclass won’t work correctly. Most of these methods call 
SubdassResponsibility rather than leaving the method empty. When 

the symbol_ TCL_DEBUG _is defined, this method displays a debugging 

message. 

procedure GetClassName (var className: Str255); 
void GetClassName (Str255 className); 

Place the name of this class in className. 
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Introduction 

CPane is an abstract class that defines a drawing area within a window or 
within another pane. In the THINK Class Library, all drawing is done within 
a pane. Each pane has its own drawing environment and coordinate system. 

Heritage 

Superclass CView 

Subclasses CControl 

CPanorama 

CRadioGroupPane 

CScrollPane 

CSizeBox 


Using CPane 

Use a pane when you need a non-scrolling area to draw in within a window. 
If you need a scrollable area, use CPanorama and CScrollPane. If you need a 
pane for displaying text, see CAbstractText or CEditText. 

Your application must define a subclass of CPane (or one of its descendants) 
to draw in a window. In your subclass, you need to override or define these 
methods: 

initialization method Free 

Draw DoCliclc 

Your pane class should have an initialization method. If your subclass de¬ 
fines new instance variables, this is the method that sets them up. By con¬ 
vention, the name of your initialization method should be I YourPane where 
YourPane is the name of your pane class. Your initialization method should 
call IPane. The supervisor of a pane should be either the pane that encloses 
it or the director its window belongs to. 
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The pane initialization method is where you set the pane’s location in its en¬ 
closure and its characteristics. If you want your pane, or any of the panes it 
encloses, to receive clicks, be sure to send the pane a 
SetWantsClicks (true) message, otherwise mouse clicks in your pane 
are ignored. 

If your pane allocates memory, you should also override the Free method 
to deallocate it. Be sure that your method calls inherited Free to 
make sure that the pane is disposed of properly. 

l*he Draw message tells your pane to draw its contents. You can assume that 
the port, clip region, and coordinate system have been set up correctly. If 
your pane uses long coordinates, you need to map from frame coordinates 
to QuickDraw coordinates before you do any drawing. 

When the user clicks in your pane, it gets a DoClick message. Your 
DoClick method can either handle the mouse click itself, or it can create a 
task and send it in a TrackMouse message. To learn more about mouse 
tracking in a pane, see CMouseTask on page 309. 

Coordinate Systems in Panes 

Panes use two of the coordinate systems in the THINK Class Library: Frame 
coordinates and QuickDraw Coordinates. 

Frame coordinates provide a local coordinate system for a pane. Units in 
frame coordinates are in pixels, and the point (0, 0) is usually the top, left 
corner of the pane. If the pane moves within its enclosure, the coordinate 
system does not change; the top left corner is still (0, 0). The only time this 
origin point changes is when you scroll the pane. Each pane can choose to 
use long coordinates or short coordinates. 

All drawing and mouse tracking is done in QuickDraw coordinates. This is 
the coordinate system that the Macintosh Toolbox uses for its drawing oper¬ 
ations. QuickDraw coordinates are only valid after a call to Prepare.The 
relationship between QuickDraw coordinates and the other coordinate sys¬ 
tems depends on whether a pane is using long frame coordinates or short 
frame coordinates. 

Short coordinates map directly to QuickDraw coordinates. Each element in a 
short coordinate uses 16 -bit values, so a pane that uses short coordinates is 
limited to the rectangle (-32768, -32768, 32767, 32767). Long coordinates 
layer a 32-bit coordinate system on top of the QuickDraw 16-bit coordinates. 
The long coordinate system lets you use a much larger coordinate area for 
your pane. Since all drawing takes place in QuickDraw coordinates you 
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have to map the long coordinates to QuickDraw coordinates when you 
draw in a pane. 

If a pane uses long coordinates, the instance variable fUsingLongCoord, 
which CPane inherits from CView is TRUE. Otherwise, fUsingLongCoord 
is FALSE. The default is to not use long coordinates. 

Hie THINK Class Library uses the types LongRect and LongPt for both 
long and short corrdinates. You’ll notice that most of the descendants of 
CView that work with points and rectangles use these types. 


Note 

If you’ve worked with earlier versions of the THINK Class 
Library, this is the biggest change you’ll notice since it will 
require some changes to your programs. 


These two types are defined like this in LongCoordinates . h in C: 

typedef struct LongPt 
{ 

long v, h; 

} LongPt; 

typedef struct LongRect 
{ 

long top, left, bottom, right; 

} LongRect; 

And like this in TCL. p in Pascal: 
type 

LongPt = record 

case integer of 
1 : ( 

v, h: longint 
) ; 

2: ( 

vh: array[VHSelect] of longint 
) ; 

end; 
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LongRect = record 

case integer of 
1 : ( 

top, left, 

bottom, right: longint 
) ; 

2 : ( 

topLeft: LongPt; 
botRight: LongPt 
); 

end; 

If the pane is using short coordinates, frame coordinates and QuickDraw co- 
ordiantes are identical, so the values stored in a LongRect or in a LongPt 
are in QuickDraw coordinates. To use them with QuickDraw routines, how¬ 
ever, you’ll need to convert them to the QuickDraw types Rect and Point. 
The THINK Class Library provides several utility routines to do these conver¬ 
sions. For a complete listing, see “Long Coordinate Utilities” on page 462. 

Drawing in Panes 

To draw in a pane use the standard QuickDraw routines. The pane’s 
P repare method sets up the QuickDraw port. If your pane uses short coor¬ 
dinates, you the coordinate system is set up correctly. If your pane uses long 
coordinates, you need to transform frame coordinates to QuickDraw coordi¬ 
nates before you draw. You can CPane methods FrameToQD and Frame- 
ToQDR convert frame points and rectangles to QuickDraw points and 
rectangles. 

Here’s an example. The following Draw method draws a line from the top, 
left of the pane to the bottom right, and then draws a rectangle inset 10 pix¬ 
els from the edges of the frame. 

In C it looks like this: 

void CCoolPane::Draw (Rect *area) 

{ 

Rect theRect; 

MoveTo(frame.left, frame.top); 

LineTo(frame.right, frame.bottom); 

LongToQDRect(&frame, StheRect); 

InsetRect(StheRect, 10, 10); 

FrameRect(&theRect); 

1 

In Pascal, the same method looks like this: 
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procedure CCoolPane.Draw (var area: Rect); 
var 

theRect: Rect; 

begin 

MoveTo(frame.left, frame.top); 

LineTo(frame.right, frame.bottom) ; 

LongToQDRect(frame, theRect); 

InsetRect(theRect, 10, 10); 

FrameRect(theRect) 
end; 

Note that to draw the line from one corner to the other, you can use the val¬ 
ues directly since they’re QuickDraw values. But to perform an operation on 
a rectangle, you have to convert the LongRect into a QuickDraw Rect. 

If a pane uses long coordinates, all coordinates are in frame coordinates. Be¬ 
fore you can do any drawing, you need to map those values to the Quick¬ 
Draw space on the screen. The CPane methods FrameToQD and 
FrameToQDR map frame coordinates into QuickDraw coordinates. 

For example, imagine you have a pane that uses long coordinates and you 
want its Draw method to display the text “Hello World.” and then draw a 
rectangle inset 10 pixels from the frame. The location of the string is in an in¬ 
stance variable called stringLoc which is declared as a LongPt. The lo¬ 
cation in stringLoc could be well outside QuickDraw coordinate space. It 
might be at (100000, 100000). 

This is how you might write the Draw method in C: 

void CMyLongPane::Draw (Rect *area) 

{ 

Point qdLoc; 

Rect qdRect; 

FrameToQD(&stringLoc, &qdLoc); 

MoveTo(qdLoc.h, qdLoc.v); 

DrawString("\pHello World.”); 

FrameToQDR(&frame, &qdRect); 

InsetRect(&qdRect, 10, 10); 

FrameRect(&qdRect); 

1 
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In Pascal it would look like this: 

procedure CMyLongPane.Draw (var area: Rect); 
var 

qdLoc: Point; 
qdRect: Rect; 

begin 

FrameToQD(stringLoc, qdLoc); 

MoveTo(qdLoc.h, qdLoc.v); 

DrawString('Hello World.'); 

FrameToQDR(frame, qdRect); 

InsetRect(qdRect, 10, 10); 

FrameRect(qdRect) 
end; 

Keep in mind the difference between converting long-coordinate structures 
to QuickDraw structures and mapping long-coordinate structures to Quick¬ 
Draw structures. When you’re using short coordinates, frame coordinates 
are the same as QuickDraw coordinates, so all you have to do is translate on 
data structure to another. When you’re using long coordinates, you need to 
map a portion of long coordinate space into QuickDraw space so you can 
draw in it. 


Variables 



Variable 

Type 

Description 

width 

integer 

Horizontal size in 
pixels. 

height 

integer 

Vertical size in pix¬ 
els. 

hEncl 

longint 

Horizontal location 
in enclosure. 

vEncl 

longint 

Vertical location in 
enclosure. 

hSizing 

SizingOption 

Horizontal sizing op¬ 
tion. 

vSizing 

SizingOption 

Vertical sizing op¬ 
tion. 

autoRefresh 

Boolean 

Refresh after a re¬ 
size? 

frame 

LongRect 

Area for displaying 
the pane which de- 
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aperture 

LongRect 

fines the frame coor¬ 
dinates. 

Active drawing area 

hOrigin 

longint 

of the pane. 

Window left in frame 

vOrigin 

longint 

coordinates. 

Window top in 

itsEnvironment 

CEnvironment 

frame coordinates. 
Drawing environ¬ 

printClip 

ClipOption 

ment. 

The region to clip to 

printing 

Boolean 

when printing. 

Is printing in 

itsBorder 

CPaneBorder 

progress? 

Border of this pane. 


Methods 

Construction/Destruction methods 

IPane procedure IPane (anEnclosure: CView; 

aSupervisor: CBureaucrat; 
aWidth, aHeight: integer; 
aHEncl, aVEncl: integer; 
aHSizing, aVSizing: SizingOption); 

void IPane (CView *anEnclosure, 

CBureaucrat *aSupervisor, 
short aWidth, short aHeight, 
short aHEncl, short aVEncl, 

SizingOption aHSizing, SizingOption aVSizing); 

Initialize a pane. Almost all of the descendants of CPane use the same argu¬ 
ments in their initialization methods. 

AnEnclosure is the enclosing view that contains this pane. Typically the 
enclosure is either a window or another pane. If your pane is a panorama, its 
enclosure should be a scroll pane. 

ASupervisor is the bureaucrat that handles all the commands that this 
pane won’t. Typically, the supervisor is the document (or director) associat¬ 
ed with this pane’s window. 

AWidth and aHeight are the width and height of the pane in pixels. 
AHEncl and aVEncl are the horizontal and vertical position of the pane 
within its enclosure. 
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The aHSizing and aVSizing parameters specify what happens to the 
pane when the size of its enclosure changes. The length and height of a 
pane changes relative to its original position in the enclosing pane. These 
are the values that aHSizing can have: 


aHSizing value 

sizFIXEDLEFT 


sizFIXEDRIGHT 


sizFIXEDSTICKY 


sizELASTIC 


Meaning 

The left edge of the pane is always the 
same number of pixels from the left edge 
of the enclosing pane as when it was orig¬ 
inally placed. 

The right edge of the pane is always the 
same number of pixels from the right edge 
of the enclosing pane as when it was orig¬ 
inally placed. 

The left and right edges stick to their origi¬ 
nal locations in the enclosing pane. If the 
enclosure scrolls horizontally, the pane 
will scroll with it. 

The width of the pane grows and shrinks 
by the same amount as the enclosing 
pane. 


These are the values the aVSizing can have: 


aVSizing value Meaning 

sizFlXEDTOP The top edge of the pane is always the 

same number of pixels from the top edge 
of the enclosing pane as when it was orig¬ 
inally placed. 

s i z FI XEDBOTTOM The bottom edge of the pane is always the 

same number of pixels from the bottom 
edge of the enclosing pane as when it was 
originally placed. 

sizFIXED STICKY The top and bottom edges stick to their 

original locations in the enclosing pane. If 
the enclosure scrolls vertically, the pane 
will scroll with it. 

sizELASTIC The height of the pane grows and shrinks 

by the same amount as the enclosing 
pane. 

A couple of examples will make this clearer: A vertical scroll bar in a win¬ 
dow would be horizontally sizFIXEDRIGHT and vertically sizELASTIC. 
It has a fixed horizontal length and remains anchored to the right edge of the 
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You may want to look at 
Figure 7-5 on page 83. 


IViewRes 


IViewTemp 


Free/Dispose 


SetFrameOrigin 


GetFrame 


- -- ♦ 

window. Vertically, it stretches and contracts with the height of the window. 
A status box in the lower left corner of a window would be s i zFIXEDLEFT 
horizontally and s izFIXEDBOTTOM vertically. It has a constant size and re¬ 
mains anchored to the bottom left corner of the window. 

procedure IViewRes (rType: ResType; resID: integer; 
anEnclosure: CView; aSupervisor: CBureaucrat); 

void IViewRes (ResType rType, short resID, 

CView *anEnclosure, CBureaucrat *aSupervisor); 

Initialize a pane from a resource template. RType is the resource type for 
the CView subclass you want to initialize. ResID is the resource ID of the re¬ 
source. AnEnclosure and aSupervisor are the same as for IBorder. 
This method is inherited from CView. 

To initialize a pane from a resource file, use a 'Pane' resource. 

procedure IViewTemp (anEnclosure: CView; 

aSupervisor: CBureaucrat; viewData: Ptr); 

void IViewTemp (CView ^anEnclosure, 

CBureaucrat *aSupervisor, Ptr viewData); 

This method is used internally for initializing from a resource template. Each 
subclass of CView overrides this method to use its own resource template. 

procedure Free; 
void Dispose (void); 

Dispose of a pane. If you create a subclass of class CPane, be sure your 
class’s Free or Dispose method calls the inherited method as well. 

Accessing methods 

procedure SetFrameOrigin (fLeft, fTop: longint); 
void SetFrameOrigin (long fLeft, long fTop); 

Set the coordinates of the top left corner of the pane’s frame to determine 
the frame coordinates of the pane. 

procedure GetFrame (var theFrame: LongRect); 
void GetFrame (LongRect *theFrame); 

Get the frame of the pane. The frame is the rectangle that encloses the pane 
in pane coordinates. Usually the top and left of this rectangle are 0,0. 
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GetLengths 


GetOrigin 


GetAperture 


Contains 


ReallyVisible 


GetPixelExtent 


procedure GetLengths (var theWidth, theHeight: 
integer); 

void GetLengths (short *theWidth, short *theHeight); 
Get the width and the height of the pane. 

procedure GetOrigin (var theHOrigin, theVOrigin: 
longint); 

void GetOrigin (long *theHOrigin, long *theVOrigin); 

Get the origin of a pane. The origin of a pane is the top left of the window in 
frame coordinates. It’s the distance from the top left of the window to the 
(0,0) of the pane. You should not use or override this method. 

procedure GetAperture (var theAperture: LongRect); 
void GetAperture (LongRect *theAperture); 

Get the aperture of the pane. The aperture is the visible portion of a pane 
where drawing can occur. The aperture is given in frame coordinates. 

function Contains (windPt: Point): Boolean; 

Boolean Contains (Point windPt); 

Returns TRUE if windPt is in the aperture of the pane. WindPt is given in 
window coordinates. 

function ReallyVisible: Boolean; 

Boolean ReallyVisible (void); 

Return TRUE if the pane is visible and within QuickDraw space. This meth¬ 
od actually returns TRUE if the pane and its enclosure is potentially visible. 
The pane may not actually be on the screen. A pane is on the screen if it’s 
ReallyVisible and the aperture isn’t empty. 

procedure GetPixelExtent (var hExtent, 
vExtent: longint); 

void GetPixelExtent (long *hExtent, long *vExtent); 

Get the dimensions of the pane in pixels. 
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SetPrintClip 


GetWindow 


SetBorder 


SetResBorder 


GetBorder 


GetHelpResID 


Show 


- ♦ 

procedure SetPrintClip (aPrintClip: ClipOption); 
void SetPrintClip (ClipOption aPrintClip); 

Specify the print option to use when printing. APrintClip can be one of 

aPrintClip value Meaning 

cl ip APERTURE Print only what is visible 

clipFRAME Print the contents of the frame 

clipPAGE Print to fill the page 

The default is clipFRAME. 

function GetWindow: CWindow; 

CWindow *GetWindow (void); 

Return the window that encloses the pane. Note that this method returns a 
window object, not a Macintosh window. 

procedure SetBorder (aBorder: CPaneBorder); 
void SetBorder (CPaneBorder *aBorder) 

Set the border for this pane. For more information about borders, see the de¬ 
scription of CPaneBorder on page 335. 

procedure SetResBorder (resID: integer); 
void SetResBorder (short resID) 

Create a border for this pane from a ' PBrd' resource whose ID is res ID. 

function GetBorder: CPaneBorder; 

CPaneBorder *GetBorder (void) 

Return the border for this pane. 

function GetHelpResID: integer; 
short GetHelpResID (void) 

Return the ID of the ' href resource that has the Balloon Help information 
for this pane. The resource ID is actually stored in the window object that 
encloses this pane. For more information about help resources for panes see 
“Using Balloon Help with views” on page 436. 

Appearance methods 

procedure Show; 
void Show (void); 

Show the pane if it was hidden. The default method sends a Ref resh mes¬ 
sage to the pane after making it visible. 
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Hide 

Place 


Offset 


ChangeSize 

AdjustToEndosure 

AdjustHoriz 


AdjustVert 


procedure Hide; 
void Hide (void); 

Hide the pane if it was visible. The default method sends a Refresh mes¬ 
sage to the pane before hiding it. 

Size and location methods 

procedure Place (hEncl, vEncl: longint; 
redraw: Boolean); 

void Place (long hEncl, long vEncl, Boolean redraw); 

Place the pane at the point hEncl, vEncl of its enclosure. HEncl and 
vEncl are given in the coordinate system of the enclosure. If redraw is 
TRUE, redraw the pane after moving it. 

procedure Offset (hOffset, vOffset: longint; 
redraw: Boolean); 

void Offset (long hOffset, long vOffset, 

Boolean redraw); 

Offset the pane by hOffset pixels horizontally and vOffset pixels verti¬ 
cally. If redraw is TRUE, redraw the pane after moving it. 

procedure ChangeSize (delta: Rect; redraw: Boolean); 
void ChangeSize (Rect *delta. Boolean redraw); 

Change the size of the pane. The values of each field of the delta rectangle 
specify how each side should change. Positive values mean down and to the 
right. Negative values mean up and to the left. 

procedure AdjustToEndosure (deltaEncl: Rect); 
void AdjustToEndosure (Rect *deltaEncl) ; 

Adjust the size or location of the pane when the enclosure has moved or 
changed size. You should not override or use this method. 

procedure AdjustHoriz (deltaEncl: Rect; 
var delta: Rect; var offset: integer; 
var moved: Boolean; var sized: Boolean); 

void AdjustHoriz (Rect *deltaEncl, Rect *delta, 

short *offset. Boolean *moved, Boolean *sized); 

Adjust the horizontal size or location of a pane. You should not override or 
use this method. 

procedure AdjustVert (deltaEncl: Rect; 
var delta: Rect; var offset: integer; 
var moved: Boolean; var sized: Boolean); 
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EndosureScrolled 


FitToEndosure 


FitToEncIFrame 


CenterWithinEndosure 
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void AdjustVert (Rect *deltaEncl, Rect *delta, 

short *offset, Boolean *moved, Boolean *sized); 

Adjust the vertical size or location of a pane. You should not override or use 
this method. 

procedure EndosureScrolled (hOffset, vOffset: 
longint); 

void EndosureScrolled (long hOffset, long vOffset) ; 

Adjust the location of a pane after its location has scrolled. This method af¬ 
fects the pane only if it is sticky in the direction it is being moved. You 
should not use or override this method. 

Adapting methods 

procedure FitToEndosure (horizFit, vertFit: Boolean); 

void FitToEndosure (Boolean horizFit, 

Boolean vertFit); 

Make the frame of the pane fit the interior of its enclosure in either the verti¬ 
cal or horizontal direction. If horizFit is TRUE, the left edge and width of 
the pane’s frame change to coincide with the enclosure’s interior. If 
vertFit is TRUE, the top edge and height of the pane’s frame change to 
coincide with the enclosure’s interior. FitToEndosure sends the enclo¬ 
sure a Get Interior message to determine the interior of the pane. 
FitToEndosure does not redraw the pane. 

procedure FitToEncIFrame (horizFit, vertFit: Boolean); 

void FitToEncIFrame (Boolean horizFit, 

Boolean vertFit); 

Fit the frame of the pane to the frame of its enclosure in either the vertical or 
horizontal direction. If horizFit is TRUE, the left edge and the width of 
the pane’s frame change to coincide with the enclosure’s frame. If vertFit 
is TRUE, the top edge and the height of the pane’s frame change to coincide 
with the enclosure’s frame. FitToEncIFrame does not redraw the pane. 

procedure CenterWithinEndosure (horizCenter, 
vertCenter: Boolean); 

void CenterWithinEndosure (Boolean horizCenter, 
Boolean vertCenter); 

Center the pane within its enclosure horizontally or vertically. Only the loca¬ 
tion of the pane changes. The size of the pane does not change. 
CenterWithinEndosure does not redraw the pane. 
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Draw 


DrawAII 


Refresh 

RefreshRect 


Drawing methods 

procedure Draw (area: Rect); 
void Draw (Rect *area); 

Draw the contents of the pane. The area parameter specifies the portion of 
the pane that needs to be redrawn. Your subclass must override this method. 

If the pane is not using long coordinates, the area parameter is given in 
frame coordinates, which in this case are the same as QuickDraw coordi¬ 
nates. 

If the pane uses long coordinates, area is given in QuickDraw coordinates. 
Your Draw method can use QD To Frame or QDToFrameR to convert from 
QuickDraw coordinates to frame coordinates and FrameToQD and Frame- 
ToQDR to convert from frame coordinates to QuickDraw coordinates. 

procedure DrawAII (var area: Rect); 
void DrawAII (Rect *area); 

Draw the pane and all its subviews and any borders that the pane or sub¬ 
views may have. Use this method when you want to force the entire pane to 
be redrawn without waiting for an update event. Scrolling is a good exam¬ 
ple. You want to redraw the pane as soon as it has scrolled instead of wait¬ 
ing for an update event. This method prepares the pane before sending 
Draw messages to it and to its subpanes. You should not override this meth¬ 
od. Look at the implementation of CPanorama’s Scroll method for an ex¬ 
ample of using DrawAII. 

procedure Refresh; 
void Refresh (void); 

Force the pane to redraw itself on the next update event. Default method 
sends a Ref reshLongRect message to the pane using the frame as the 
area. 

procedure RefreshRect (area: Rect); 
void RefreshRect (Rect *area); 

Force a portion of the pane to redraw itself on the next update event. Area 
is a Rect in frame coordinates. Only the portion of the pane that’s actually 
visible will actually be redrawn. 
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RefreshLongRect 


RefreshBorder 


Paginate 


AboutToPrint 


PrintPage 


DonePrinting 


procedure RefreshLongRect (area: LongRect); 
void RefreshLongRect (LongRect *area); 

Force a portion of the pane to redraw itself on the next update event. Area 
is a LongRect in frame coordinates. Only the portion of the pane that’s ac¬ 
tually visible will actually be redrawn. 

procedure RefreshBorder; 
void RefreshBorder (void); 

Force the pane’s border to redraw itself on the next update event. 

Printing methods 

procedure Paginate (aPrinter: CPrinter; 
pageWidth, pageHeight: integer); 

void Paginate (CPrinter *aPrinter, short pageWidth, 
short pageHeight); 

Set up the pane’s pagination. By default, panes print only on one page. The 
document that a pane belongs to sends this message to the pane. For exam¬ 
ples more complex pagination, see CAbstractText and CPanorama. 

procedure AboutToPrint (var firstPage, lastPage: 
integer); 

void AboutToPrint (short *firstPage, short *lastPage); 

Printing is about to begin. Your pane subclass can override this method to 
do anything that needs to happen right before printing. 

procedure PrintPage (pageNum, pageWidth, pageHeight: 
integer; aPrinter: CPrinter); 

void PrintPage (short pageNum, short pageWidth, 
short pageHeight, CPrinter *aPrinter); 

Print the specified page of the pane. By default, panes have only on page. 
APrinter is usually supplied by the document that this pane belongs to. If 
your pane subclass supports multi-page documents, you must override this 
method to determine which part of the pane to draw. 

procedure DonePrinting; 
void DonePrinting (void); 

Printing is over. If you want to take any action when printing is done, over¬ 
ride this method. 
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PrepareToPrint 


Prepare 


RestoreE n vi ron m en t 


CalcFrame 


ResizeFrame 


procedure PrepareToPrint; 
void PrepareToPrint (void); 

Set up the coordinate system and the clipping region before printing. The 
default method sets the clipping region to the region described in the 
printClip variable. You can set this variable with the SetPrintClip 
method. 

Calibration methods 

procedure Prepare; 
void Prepare (void); 

Prepare the pane for drawing. Prepare sets up the port and the Quick¬ 
Draw coordinates for the pane, converting Ion coordinates to QuickDraw 
coordinates if necessary. It also sets the clipping region to the aperture (the 
visible portion of the pane) so drawing is constrained to the visible portion 
of the pane. If the pane has an environment associated with it, Prepare 
sends a Restore message to the environment. If the pane is being printed, 
the default method sends the pane a PrepareToPrint message instead. 

The inherited Prepare method in CViewsets cPreparedView to this 
view. If this view gets another Prepare message, Prepare avoids setting 
up the drawing environment all over again. 

procedure RestoreEnvironment; 
void RestoreEnvironment (void); 

Restore the pane’s drawing environment. If the pane has a drawing environ¬ 
ment associated with it, this method sends a Restore message to it. 

procedure CalcFrame; 
void CalcFrame (void); 

Calculate the coordinates of the pane’s frame based on the frame’s width 
and height and its location within its enclosure. Generally, the superclasses 
of the pane classes you define will send this message. You should not use or 
override this method unless your pane subclass needs something other than 
(0,0) at its top left corner 

procedure ResizeFrame (delta: Rect); 
void ResizeFrame (Rect *delta); 

Adjust the frame when the size of the pane changes. The delta rectangle 
specifies how each side changes. Positive values mean down and to the 
right. Negative values mean up and to the left. The default method always 
sets the top left of the frame to (0,0) 
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CalcAperture 


TrackMouse 


To learn more about mouse 
trackingand mouse tasks, 
see the class CMouseTask 
on page 309. 


WindToFrame 


--- 4 

You should not need to use or override this method unless your pane sub¬ 
class requires that the top, left of the frame be something other than (0,0). 
See the implementation of ResizeFrame in CPanorama for an example. 

procedure CalcAperture; 
void CalcAperture (void); 

Calculate the visible (or drawable) portion of a pane. The aperture of a pane 
is the area that is not obscured by the bounds of the enclosing view. You 
should not use or override this method. To get the aperture, use 
GetAperture on page 324. 

Cursor method 

procedure TrackMouse (theTask: CMouseTask; 
startPt: LongPt; var pinRect: LongRect); 

void TrackMouse (CMouseTask *theTask, LongPt startPt, 
LongRect *pinRect); 

Track the mouse in this view. TheTask is a mouse task that you create. 
StartPt is the starting point in frame coordinates. PinRect is a constrain¬ 
ing rectangle in frame coordinates. This message is usually sent from a 
DoClick method. 

The default method does several things: 

• Sends a Prepare message to the view 

• Sends a BeginTracking message to theTask 

• Sends a KeepTracking message to theTask as long as the 
mouse is down. The current point is constrained to pinRect. 

(Your task subclass must override the KeepTracking method.) 

• Sends an EndTracking message to theTask. (Your task sub¬ 
class must override this method as well.) 

Coordinate transformation methods 

procedure WindToFrame (windPt: Point; 
var framePt: LongPt); 

void WindToFrame (Point windPt, LongPt *framePt); 
Convert the point windPt from window coordinates to frame coordinates 
and place the converted point in framePt. 
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WindToFrameR 


FrameToWind 


FrameToWindR 


EndToFrame 


EndToFrameR 


FrameToEnd 


FrameToEndR 


procedure WindToFrameR (windRect: Rect, 
var frameRect: LongRect); 

void WindToFrameR (Rect *windRect, 

LongRect *frameRect); 

Convert the rectangle windRect from window coordinates to frame coordi¬ 
nates and place the converted rectangle in f rameRect. 

procedure FrameToWind (framePt: LongPt; 
var windPt: Point); 

void FrameToWind (LongPt *framePt, Point *windPt); 
Convert the point framePt from frame coordinates to window coordinates 
and place the converted point in windPt. 

procedure FrameToWindR (frameRect: LongRect; 
var windRect: Rect); 

void FrameToWindR (LongRect *frameRect, 

Rect *windRect); 

Convert the rectangle f rameRect from frame coordinates to window coor¬ 
dinates and place the converted rectangle in windRect. 

procedure EndToFrame (var thePoint: LongPt); 
void EndToFrame (LongPt *thePoint) ; 

Convert a point from the frame coordinates of its enclosure to the frame co¬ 
ordinates of the pane. 

procedure EndToFrameR (var theRect: LongRect); 
void EndToFrameR (LongRect *theRect) ; 

Convert a rectangle from the frame coordinates of its enclosure to the frame 
coordinates of the pane. 

procedure FrameToEnd (var thePoint: LongPt); 
void FrameToEnd (LongPt *thePoint); 

Convert a point from frame coordinates to the frame coordinates of its enclo¬ 
sure. 

procedure FrameToEndR (var theRect: LongRect); 
void FrameToEndR (LongRect *theRect) ; 

Convert a rectangle from frame coordinates to the frame coordinates of its 
enclosure. 
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FrameToGlobaIR 


QDToFrame 


QDToFrameR 


FrameToQD 


FrameToQDR 


SectAperture 


procedure FrameToGlobaIR (frameRect: LongRect; 
globalRect: Rect); 

void FrameToGlobaIR (LongRect *frameRect, 

Rect *globalRect); 

Convert the rectangle frameRect from frame coordinates to global coordi¬ 
nates and place the converted rectangle in globalRect. 

procedure QDToFrame (qdPoint: Point; 
var framePt: LongPt); 

void QDToFrame (Point qdPoint, LongPt *framePt); 

Convert qdPoint from QuickDraw coordinates to frame coordinates, and 
put the result in framePt. QdPoint is assumed to be in the portion of 
QuickDraw space that the pane is mapping to. If the pane is not using long 
coordinates, the values in qdPoint and f ramePoint are the same. 

procedure QDToFrameR (qdRect: Rect; 
var frameRect: LongRect); 

void QDToFrameR (Rect *qdRect, LongRect *frameRect); 
Convert qdRect from QuickDraw coordinates to frame coordinates, and 
put the result in frameRect. 

procedure FrameToQD (framePt: LongPt; 
var qdPt: Point); 

void FrameToQD (LongPt *framePt, *Point qdPt); 

Convert framePt from frame coordinates to QuickDraw coordinates, and 
put the results in qdPoint. 

procedure FrameToQDR (frameRect: LongRect; 
var qdRect: Rect); 

void FrameToQDR (LongRect *frameRect, Rect *qdRect); 
Convert frameRect from frame coordinates to QuickDraw coorinates, and 
put the result in qdRect. 

function SectAperture (srcRect: LongRect; 
var destRect: Rect): Boolean; 

Boolean SectAperture (LongRect *srcRect, 

Rect *destRect); 

Clip the srcRect (in frame coorindate) to the pixels visible through the ap¬ 
erture, and return the result in a QuickDraw rectangle, destRect. If 
destRect is not empty, this method returns TRUE. 
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CPaneBorder t 

44 


Introduction 

CPaneBorder is a class that draws a border around a pane. 

Heritage 

Superclass CObject 

Subclasses None 

Using CPaneBorder 

CPaneBorder draws a border around a pane. You can choose from several 
types, including a rectangle, a rectangle with a shadow, and a rounded rect¬ 
angle. If you need a different type, create a subclass of CPaneBorder. This 
class doesn’t use any coordinate system. Its parameters are described as off¬ 
sets from the pane’s frame. 

To give a pane a border, create an instance of CPaneBorder and send the 
pane a SetBorder message, with your border as the argument. The pane 
takes care of drawing it. When the size of the pane changes, the size of the 
border changes automatically. If you want to access the border to change it, 
send the pane a GetBorder message. 

When you initialize the border with IPaneBorder, you set its shape. These 
are the available shapes: 

Name 

kBo rde rF r ame 
kBorderRoundRect 
kBorderOval 
kBorderLeft 
kBorderTop 
kBorderRight 
kBorderBottom 
kBorderNone 


Description 

Rectangle 
Rounded rectangle 
Oval 

Line on left side 
Line on top side 
Line on right side 
Line on bottom 
No border 
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You can add together kBorderLef t, kBorderTop, kBorderRight, and 
kBroderBottom to create new shapes. For example, kBorderTop + 
kBorderRight gives you a border with lines on the top and right of the 
pane. To create yet more shapes, you need to subclass CPaneBorder. 

After you initialize your border, you can change its attributes, like the width 
of the border outline, the distance between the border outline and the 
frame, and whether there’s a shadow. Figure 44-1 shows you the instance 
variables that control these attributes: 


margin 

borderPen 

shadowPen 


The Frame 


hi 

II 

H 


shadowOffset 


Figure 44-1 A pane border 


This table describes what these instance variables control and the methods 
to set them: 


Variable 

margin 

borderPen 

doShadow 

shadowPen 

shadowOffset 


Method 

SetMargin 

SetPenSize 

SetShadow 

SetShadow 

SetShadow 


Description 

Distance between the 
frame and the border. 
Width of the pen used to 
draw the border. 

TRUE, if this border has a 
shadow. 

Width of the pen used to 
draw the shadow. 

Distance between the bor¬ 
der and its shadow. 
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Variables 


♦ 


This table describes other instance variables that control the border’s ap¬ 
pearance: 


Variable 

borderFlags 

penpat 

roundDiameter 


Method 

SetBorderFlags 

SetPattern 

SetRounding 


Description 

The shape of the 
border. 

The pattern used to 
draw the border and 
shadow. 

The roundness of the 
border’s corners, if 
the shape is a round¬ 
ed rectangle. 


Variables 

These are internal instance variables. You can access them with the access¬ 
ing methods described below. Only subclasses of CPaneBorder should refer 
to them directly. In THINK C, the instance variables are protected. 


Variable 

Type 

Description 

borderFlags 

long 

The shape of the 
border. 

borderPen 

Point 

The width of the pen 
used to draw the 
border. 

shadowOffset 

Point 

The distance be¬ 
tween the border 
and its shadow. 

shadowPen 

Point 

The width of the pen 
used to draw the 
shadow. 

doShadow 

Boolean 

TRUE if shadow is 
drawn. 

roundDiameter 

Point 

The roundness of the 
border’s corners, if 
the shape is a round¬ 
ed rectangle. 

penPat 

Pattern 

The pattern used to 
draw the border and 
shadow.. 

margin 

Rect 

The distance be¬ 
tween the frame and 
the border. 
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IPaneBorder 


IResPaneBorder 


SetPattern 


GetPattern 


SetBorderFlags 


GetBorderFlags 


SetPenSize 


GetPenSize 


Methods 

Creation and destruction 

procedure IPaneBorder (borderFlags: integer); 
void IPaneBorder (short borderFlags); 

Initialize a pane border. The borderFlags describe the shape of the bor¬ 
der. It can be one of these :kBorderNone, kBorderLef t, kBorderTop, 
kBorderRight, kBorderBottom, kBorderOval, kBorderRoun- 
dRect, kBorderFrame. All the defaults maybe changed via methods. 

procedure IResPaneBorder (resID: integer); 
void IResPaneBorder (short resID); 

Initialize a border from a ' PBrd' resource. 

Accessing methods 

procedure SetPattern (aPattern: Pattern); 
void SetPattern (Pattern aPattern); 

Set the pattern used for drawing the border’s outline and its shadow. 

procedure GetPattern (var aPattern: Pattern); 
void GetPattern (Pattern aPattern); 

Return the current pattern. 

procedure SetBorderFlags (aBorderFlags: integer); 
void SetBorderFlags (short aBorderFlags); 

Set the border flags. ABorderFlags can be one of these: kBorderNone, 
kBorderLeft, kBorderTop, kBorderRight, kBorderBottom, 
kBorderOval, kBorderRoundRect, kBorderFrame. 

function GetBorderFlags: longint; 
long GetBorderFlags (void); 

Return the current border flags. 

procedure SetPenSize (penWidth, penHeight: integer); 
void SetPenSize (short penWidth, short penHeight); 

Set the pen size used to draw the border. 

procedure GetPenSize (var penWidth, penHeight: 
integer); 

void GetPenSize (short *penWidth; short *penHeight); 
Return the pen size used to draw the border. 
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Methods 


SetShadow 


CetShadow 


SetRounding 


GetRounding 


SetMargin 


GetMargin 


DrawBorder 


--♦ 

procedure SetShadow (hOffset, vOffset, 
width, height: integer); 

void SetShadow (short hOffset, short vOffset, 
short width, short height); 

Set the shadow attributes. HOffset and vOffset specify the distance of 
the shadow from the border outline. Width and height specify the pen 
size used to draw the shadow. This method also sets doShadow to TRUE. 

function GetShadow (var hOffset, vOffset, 
width, height: integer): longint; 

long GetPenSize (short *hOffset, short *vOffset, 
short *width, short *height); 

Return the current shadow attributes. 

procedure SetRounding (hDiameter, vDiameter: integer); 
void SetRounding (short hDiameter, short vDiameter); 

Set the roundness of the corners of rounded rectangles. These are used as 
parameters to FrameRoundRect. This method also sets the border style to 
kBorderRoundRect, if that isn’t the border style already. 

procedure GetRounding (var hDiameter, vDiameter: 
integer); 

void GetRounding (short *hDiameter, short *vDiameter) ; 
Returns the current rounding diameters. 

procedure SetMargin (aMargin: Rect); 
void SetMargin (Rect *aMargin); 

Set the distance between the border outline and the frame. AMargin is a 
Rect with positive offsets for each side of the border. For example, to have 
a one pixel margin on all sides, use (1, 1, 1, 1). 

procedure GetMargin (var aMargin: Rect); 
void GetMargin (Margin *aMargin); 

Return the current border margin. 

Drawing method 

procedure DrawBorder (paneFrame: Rect); 
void DrawBorder (Rect *paneFrame); 

Draw the border. PaneFrame is the pane’s frame in the pane’s current coor¬ 
dinates. 
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CalcBorderRect 


Calibration method 

procedure CalcBorderRect (var paneFrame: Rect); 
void CalcBorderRect (Rect *paneFrame); 

Return the area for the frame and its border. PaneFrame is the pane’s frame 
in the pane’s current coordinates. This method adds to it the size of the bor¬ 
der, including the margin and shadow, on all sides. 
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CTearOffMenu is described 
on page 417. 


CPaneMDEF * 

45 


Introduction 

CPaneMDEF is an abstract class that lets you display any pane as a Macin¬ 
tosh Menu. The class includes methods for handling tear-off menus. 

Heritage 

Superclass CMenuDefProc 

Subclasses CSelectorMDEF 

Using CPaneMDEF 

CPaneMDEF’s superclass, CMenuDefProc, lets you write object-oriented 
menu definition procedures. This class and its descendants take that idea a 
step further to let you use THINK Class Library panes as menus. The pane 
that you use in a CPaneMDEF subclass should belong to a subclass of 
CTearOffMenu. 

A tear-off menu is a window that appears to float above all the other win¬ 
dows in your application. In that environment, the pane is part of the visual 
hierarchy, and it will behave just like any other pane in a window. 

When it appears as a custom menu, the pane isn’t really in the visual hierar¬ 
chy at all. As far as the pane is concerned, its enclosure is the floating win¬ 
dow it appears in when it’s torn off. When you draw a custom menu in your 
Draw method , you have to set up the QuickDraw environment by hand 
with the SetupQuickDraw method. This method changes the QuickDraw 
coordinate system so drawing takes place in pane coordinates. Be sure to 
call RestoreQuickDraw at the end of the Draw method 

Since this class doesn’t have a Choose Item method, you’ll need to create a 
subclass of CPaneMDEF that handles item selection. The class 
CSelectorMDEF is a subclass of CPaneMDEF that lets you use selectors as 
menus. It’s also a good class to study to learn how to write a Choose Item 
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♦ 


method. Your Choose Item method should also use the SetupQuick- 
Draw/RestoreQuickDraw methods. 

Variables 

Variable Type 

itsPane CPane 

itsTearOffMenu CTearOf fMenu 
savePort GrafPtr 

saved ip RgnHandle 

Methods 

Construction and destruction methods 

IPaneMDEF procedure IPaneMDEF (MDEFid: integer; 

aPane: CPane; aTearOffMenu: CTearOffMenu); 

void IPaneMDEF (short MDEFid, CPane *aPane, 
CTearOffMenu *aTearOffMenu); 

Initialize the pane MDEF. This method calls IMenuDefProc with the MDEFid. 
The instance variable itsPane is set to aPane, which is the pane that you 
want to display as a menu. ATearOf fMenu is a tear-off menu object. You 
can pass NIL if this menu is not a tear-off menu. See the CTearOffMenu class 
on page 417. 

DrawMenu procedure DrawMenu (macMenu: MenuHandle; 

menuRect: Rect); 

void DrawMenu (MenuHandle macMenu, Rect *menuRect); 

This method draws the pane as a menu. MacMenu and menuRect are pro¬ 
vided by the Macintosh Menu Manager and are in global coordinates. 
DrawMenu uses the SetupQuickDraw method to set up the QuickDraw 
drawing environment so the point (0,0) is the top, left corner of the pane. 
The method then sends itsPane a RestoreEnvironment message and 
then a Draw message to display the pane. If the menu is disabled, Draw- 
Menu grays out the menu. Finally, the method restores the QuickDraw envi¬ 
ronment. 

Unless your subclass needs to do something extraordinary to draw your 
menu, you should not override this method. 


Description 

The pane to display as a 
menu. 

The torn-off menu. 

Used internally to save the 
grafport. 

Used internally to save the 
clipping region. 
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Methods 


SizeMenu 


TearOffMenu 


This method doesn't 
change the QuickDraw co¬ 
ordinates because it expects 
to be called from 
Chooseltem which has 
already set things up. 


For a good example of a 
Chooseltem method[ 
see the CSelector class. 


♦ 


procedure SizeMenu (macMenu: MenuHandle); 
void SizeMenu (MenuHandle macMenu); 

This method is called by the Macintosh Menu Manager to determine the size 
of the menu. This method gets the height and width of the pane and stores 
them in menuWidth and menuHeight fields of macMenu. Your subclass 
should not override this method. 

procedure TearOffMenu (menuRect: Rect; 
mouseLoc: Point); 

void TearOffMenu (Rect *menuRect, Point mouseLoc); 
TearOffMenu drags a gray outline representing the menu when you tear it 
off the menu bar. The size of the gray outline is the menuRect plus the mar¬ 
gins specified in itsTearOf fMenu. You can drag the outline as long as the 
mouse is still down, and the mouse is in the tear-off region. If the mouse is in 
the tear-off region when the button is released, TearOffMenu sends a 
TornOf f message to itsTearOf fMenu to do the “tearing.” 

Unless your subclass needs to do something fancy to show that a menu is 
being torn off, you should not override this method. 

Your subclass should call this method in its Choose Item method when the 
hitPt is not in the menuRect. You should also check to make sure that 
there is a tear-off menu (itsTearOf fMenu is not NIL) and that the menu is 
not disabled. 

Here’s what this might look like in Pascal: 

procedure CMyMDEF.Chooseltem(macMenu: MenuHandle 
menuRect: Rect; hitPt: Point; 
var whichltem: integer); 
begin 

if PtlnRect(hitPt, menuRect) then 
begin 

SetupQuickDraw(menuRect); 

{ choose an item } 

RestoreQuickDraw; 

end 

else 

begin 

whichltem = NOTHING; 
if (itsTearOffMenu <> NIL) AND 
MenuEnabled(macMenu) 
then 

TearOffMenu(menuRect, hitPt) 

end 

end 
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In C it looks like this: 

void CMyMDEF::Chooseltem(MenuHandle macMenu, 
Rect *menuRect / Point hitPt, 
short *whichltem) 

{ 

if (PtlnRect(hitPt, menuRect) { 
SetupQuickDraw(menuRect); 

/* choose an item */ 

RestoreQuickDraw(); 

} else { 

*whichltem = NOTHING; 
if (itsTearOffMenu != NULL && 
MenuEnabled(macMenu)) 

TearOffMenu(menuRect, hitPt); 


PtlnTearRgn 


SetupQuickDraw 


RestoreQuickD raw 


} 

function PtlnTearRgn (hitPt: Point; 
menuRect: Rect): Boolean; 

Boolean PtlnTearRgn (Point hitPt, Rect *menuRect); 
Returns TRUE if hitPt (given in global coordinates) is in the tear-off region. 
The tear-off region is anywhere except the menu bar and within 
TEARMARGIN pixels of the menu. 

procedure SetupQuickDraw (menuRect: Rect); 
void SetupQuickDraw (Rect *menuRect); 

Set up the QuickDraw environment so the MDEF’s pane draws correctly. 
Since panes associated with MDEFs aren’t really part of the visual hierarchy, 
you have to set up the QuickDraw environment directly. This method sets 
the port to the desktop’s port and sets the origin to the top left of the pane 
and sets the clipping region to menuRect. 

procedure RestoreQuickDraw; 
void RestoreQuickDraw (void); 

Restore the QuickDraw environment to what it was before the Set¬ 
upQuickDraw call. 
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46 


Introduction 

CPanorama is an abstract class for implementing displays that may be larger 
than the frame of a pane. The frame is a viewport though which a portion of 
the panorama is visible. 

Heritage 

Superclass CPane 

Subclasses CPicture 

CStaticText 


Using CPanorama 

Use a subclass of CPanorama whenever you want to display something that 
is larger than the pane you want to view it through. For example, some pic¬ 
tures are much bigger than a standard Macintosh screen. For an example of a 
panorama, look at the CEditText class on page 269. In almost every case, 
you’ll use a panorama with a scroll pane (see CScrollPane on page 387 for a 
description). 

Drawing in a panorama is almost the same as drawing in a pane. The main 
difference is that panoramas can have their own coordinate system. Each 
panorama unit can map to one or more pixels. For example, in the CEditText 
class, the horizontal unit is set to the number of pixels in the widest charac¬ 
ter, and the vertical unit is set to the number of pixels of the height of a line. 
Scroll panes use this information to set the scroll bars accurately. 


Note 

Panoramas do not support fractional scales or non-linear 
scales for coordinate systems. 


The size of the panorama image is called the bounds. In most cases, the top, 
left corner of the bounds is the point (0,0), but it’s not required. The way to 
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♦ 


think of the relationship between the panorama and the frame of the pane is 
that the panorama image is stationary as the frame roves over it As you 
move around in a panorama, the coordinates of the top, left corner of the 
frame will change. 


Variables 



Variable 

Type 

Description 

bounds 

LongRect 

Bounds defining 

Pane coordinates. 

position 

LongPoint 

Location of frame in 
panorama. 

hScale 

integer 

Pixels per horizontal 
unit. 

vScale 

integer 

Pixels per vertical 
unit. 

savePosition 

LongPoint 

Save for later restora¬ 
tion. 

itsScrollPane 

CScrollPane 

Scroll pane a panora¬ 
ma belongs to, if 
any. 


Methods 

Construction and destruction methods 

IPanorama procedure IPanorama (anEnclosure: CView; 

aSupervisor: CBureaucrat; 
aWidth, aHeight: integer; 
aHEncl, aVEncl: integer; 
aHSizing, aVSizing: SizingOption); 

void IPanorama (CView *anEnclosure, 

CBureaucrat *aSupervisor, 
short aWidth, short aHeight, 
short aHEncl, short aVEncl, 

SizingOption aHSizing, SizingOption aVSizing); 

Initialize a panorama. The arguments to this routine are identical to the ones 
for IPane. 


Note 

The descriptions of the other arguments are in CPane on 
page 321. 
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Methods 


IViewRes 


IViewTemp 


CetExtent 


CetFramePosition 


GetFrameSpan 


SetBounds 


♦ 


procedure IViewRes (rType: ResType; resID: integer; 
anEnclosure: CView; aSupervisor: CBureaucrat); 

void IViewRes (ResType rType, short resID, 

CView *anEnclosure, CBureaucrat *aSupervisor); 

Initialize a panorama from a resource template. Rtype is the resource type 
for the CView subclass you want to initialize. Res ID is the resource ID of 
the resource. AnEnclosure and aSupervisor are the same as for 
IB order. This method is inherited from CView. 

To initialize a panorama from a resource file, use a ' Pano ' resource. 

procedure IViewTemp (anEnclosure: CView; 

aSupervisor: CBureaucrat; viewData: Ptr); 

void IViewTemp (CView *anEnclosure, 

CBureaucrat *aSupervisor, Ptr viewData); 

This method is used internally for initializing from a resource template. Each 
subclass of CView overrides this method to use its own resource template. 

Accessing methods 

procedure GetExtent (var theHExtent, theVExtent: 
longint); 

void GetExtent (long *theHExtent, long *theVExtent); 
Get the size of each side of the panorama in panorama units. 

procedure GetFramePosition (var theHPos, theVPos: 
longint); 

void GetFramePosition (long *theHPos, long *theVPos); 
Determine how far the top, left of the frame is from the top, left of the 
bounds in panorama coordinates. The CScrollPane class uses this method to 
figure out the maximum settings for the scroll bars. You should not use or 
override this method. 

procedure GetFrameSpan (var theHSpan, theVSpan: 
integer); 

void GetFrameSpan (short *theHSpan, short *theVSpan); 
Return the number of panorama units that the frame spans. 

procedure SetBounds (aBounds: LongRect); 
void SetBounds (LongRect *aBounds); 

Set the bounds of the panorama. The bounds define the size of the data dis¬ 
played in the panorama and the panorama coordinates. If the panorama’s 
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♦ 


GetBounds 


SetPosition 


GetPosition 


SetScales 


GetScales 


SetScrollPane 


enclosure is a scroll pane, this method sends it an Ad justScrollMax mes¬ 
sage to adjust the scroll bars. 

procedure GetBounds (var theBounds: LongRect); 
void GetBounds (LongRect *theBounds); 

Get the bounds of a panorama. 

procedure SetPosition (aPosition: LongPt); 
void SetPosition (LongPt aPosition); 

Set the position of the frame in relation to the panorama. The point is in pan¬ 
orama coordinates. If the panorama’s enclosure is a scroll pane, this method 
sends it a Calibrate message to adjust the position of scroll box (the scroll 
bars’ “thumb”). 

procedure GetPosition (var thePosition: LongPt); 
void GetPosition (LongPt *thePosition); 

Get the position of the frame in relation to the panorama. In other words, 
what are the panorama coordinates of the top, left of the frame? 

procedure SetScales (aHScale, aVScale: integer); 
void SetScales (short aHScale, short aVScale); 

Set the horizontal and vertical scales. Specify the scales in pixels per panora¬ 
ma unit. For instance, the CStaticText class (a subclass of CPanorama) uses 
the width of the widest character as its horizontal unit and the height of a 
line as a vertical unit. If the panorama’s enclosure is a scroll pane, this meth¬ 
od sends it an Ad justScrollMax message to adjust the scrollbars. 

procedure GetScales (var theHScale, theVScale: 
integer); 

void GetScales (short *theHScale, short *theVScale) ; 

Get the scale factors of the panorama. 

procedure SetScrollPane (aScrollPane: CScrollPane); 
void SetScrollPane (CScrollPane *aScrollPane); 

Specify the scroll pane that controls this panorama. This method is for use 
only by the CPanorama class. To associate a panorama with a scroll pane, 
use the InstallPanorama method. 
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Methods 


GetHomePosition 


GetPixelExtent 


ResizeFrame 


Scroll 


ScrollTo 


ScrollToSelection 


AutoScroll 


- —- ♦ 

procedure GetHomePosition (var theHomePos: LongPt); 
void GetHomePosition (LongPt *theHomePos); 

Get the location of the top, left corner of the panorama in panorama coordi¬ 
nates. 

procedure GetPixelExtent (var hExtent, vExtent: 
longint); 

void GetPixelExtent (long *hExtent, long *vExtent); 

Get the size of each side of the panorama in pixels. 

Calibrating methods 

procedure ResizeFrame (delta: Rect); 
void ResizeFrame (Rect *delta); 

Adjust the frame of a panorama when its size changes. The delta rectangle 
specifies the amount of change for each side. Positive numbers mean down 
and to the right. Negative numbers mean up and to the left. 

Scrolling methods 

procedure Scroll (hDelta, vDelta: longint; 
redraw: Boolean); 

void Scroll (long hDelta, long vDelta, 

Boolean redraw); 

Scroll a panorama by hDelta units horizontally and vDelta units vertical¬ 
ly. The units are given in panorama coordinates. 

procedure ScrollTo (aPosition: LongPt; 
redraw: Boolean); 

void ScrollTo (PointLongPt, Boolean redraw); 

Scroll the panorama to a specific position. The units given in aPosition 
are in panorama coordinates. 

procedure ScrollToSelection; 
void ScrollToSelection (void); 

Scroll the panorama so the selection is visible. The default method does 
nothing. Your panorama subclass must override this method. 

function AutoScroll (mouseLoc: Point): Boolean; 

Boolean AutoScroll (Point mouseLoc); 

Scroll automatically during a mouse-down. Returns TRUE if scrolling actual¬ 
ly took place. Typically, you would send this message in the same routine 
that tracks selection. 
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DoKeyDown 


Paginate 


AboutToPrlnt 


PrintPage 


DonePrinting 


procedure DoKeyDown (theChar: char; keyCode: Byte; 
macEvent: EventRecord) 

void DoKeyDown (char theChar, Byte keyCode, 

EventRecord *macEvent); 

This method supports the Home, End, Page Up, and Page Down keys of the 
extended keyboard The Home and End keys send ScrollTo messages to 
the panorama’s scroll pane to scroll to the beginning or end of the panora¬ 
ma. The Page Up and Page Down keys send Dover t Sc roll messages to 
the panorama’s scroll pane to simulate hits on the page up and page down 
regions of the scroll bar. 

Printing methods 

procedure Paginate (aPrinter: CPrinter; 
pageWidth, pageHeight: integer); 

void Paginate (CPrinter *aPrinter, short pageWidth, 
short pageHeight); 

Determine how many pages to print. The panorama is divided into horizon¬ 
tal and vertical strips of equal size. APrinter is the printing object. Typical¬ 
ly it belongs to the document that owns this panorma. 

procedure AboutToPrint (var firstPage, lastPage: 
integer); 

void AboutToPrint (short *firstPage, short *lastPage); 

The specified range of pages are about to be printed. You can override this 
method if your subclass needs to take some action before printing. 

procedure PrintPage (pageNum, pageWidth, 

pageHeight: integer; aPrinter: CPrinter); 

void PrintPage(short pageNum, short pageWidth, 
short pageHeight, CPrinter *aPrinter); 

Print the specified page. PageWidth is the width of the page in pixels. 
PageHeight is the height of the page in pixels. APrinter is the printer 
object. Typically it belongs to the document that owns this panorama. 

procedure DonePrinting; 
void DonePrinting (void); 

Printing has stopped. Override this method if you need to do some cleanup 
after printing. 
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47 


Introduction 

CPatternGrid is a subclass of CGridSelector that displays patterns in a table 
and lets you choose one. CPatternGrid is useful for implementing pattern 
palettes like MacPaint and HyperCard 

Heritage 

Superclass CGridSelector 

Subclasses None 

Using CPatternGrid 

The CPatternGrid class lets you create panes that display patterns in a table. 
The most common use for this kind of table is a pattern palette for a painting 
or drawing program. You can use a CPatternGrid as a tool palette that’s part 
of a window or as a custom tear-off menu. The Art Class demonstation pro¬ 
gram uses CPatternGrid to display it’s Patterns tear-off menu. 



Figure 47-1 Art Class uses CPatternGrid as tear-off menu. 

Unlike other subclasses of CPane that optionally let you initialize an object 
from a resource, you must use a resource to initialize a CPatternGrid. The 
first argument to the initialization method, IPatternGrid, is the resource 
ID of a ' PtGd' resource which contains the values that IPatternGrid 
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♦ 


passes up to CGridSelector’s initialization method. The 1 PtGd' resource 


looks like this: 

Field 

Size 

Description 

Rows 

integer 

The number of rows in the 

Columns 

integer 

grid. 

The number of columns in 

Box Width 

integer 

the gird. 

The width in pixels of 

Box Height 

integer 

each box. 

The height in pixels of 

Horiz. Sizing 

integer 

each box. 

Horizontal sizing option. 

Vert. Sizing 

integer 

Usually sizFIXEDLEFT 
(0) 

Vertical sizing option. Usu¬ 

Horiz. Location 

integer 

ally si zF IXEDTOP (2) 
Horizontal location of grid 

Vert. Location 

integer 

in its enclosure. 

Vertical location of grid in 

Command base 

integer 

its enclosure. 

The command base for 

Pattern List ID 

integer 

turning selections into 
command numbers. 

The resource ID of the pat¬ 

Number of patterns 

integer 

tern list resource (PAT#) 
to use. 

The number of patterns to 

Pattern indices 

integer 

display. 

The index in the PAT# re- 


source to display. One en¬ 
try for each pattern. 


The first nine fields are the same as the arguments that you pass to 
The standard pattern list is IGridSelector. The last three are specific to pattern grids. The Pattern 
in the System file. Its re- List ID specifies which pattern list resource (' PAT# 1 ) the pattern grid 

source ID is zero. should use. The Number of patterns field is how many of the patterns in the 

list to use. The Pattern indices are the indices of a pattern in the pattern list. 

The file TCL TMPLs contains ResEdit templates (TMPL resources) that help 
you create and edit PtGd resources. This is what the 1 PtGd * resource in Art 
Class looks like when you edit it with ResEdit. 
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IPatternGrid 


♦ 


EH PtGd “Patterns" ID ■ 102 from Rrt Class.if.RSRC Htf 
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Figure 47-2 The PtGd resource in Art Class 

Variables 


Variable Type 

patListID integer 

numPats integer 

thePatterns Handle 


Description 

The ID of the ' PAT# ' re¬ 
source to use. 

Number of patterns to use 
Handle to the list of 
1 PAT# ' resource indices. 


Methods 

Construction methods 

procedure IPatternGrid (PtGdid: integer; 

anEnclosure: CView; aSupervisor: CBureaucrat); 

void IPatternGrid (short PtGdid, CView *anEnclosure, 
CBureaucrat *aSupervisor); 

Initialize the character grid. PtGdid is the resource ID of the 'PtGd' re¬ 
source that describes the location of the pane and pattern list to use for the 
grid. See “Using CPatternGrid” above for the details on 'PtGd' resources. 
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Free/Dispose 


Drawl tem 


Hiliteltem 


GetPattern 


procedure Free; 
void Dispose (void); 

Dispose of the index list and the object. 

Drawing methods 

procedure Drawltem (theltem: integer; 
theBox: Rect); 

void Drawltem (short theltem, Rect *theBox); 

Draw pattern numbered theltem so it fills the box. Remember that the 
theltem doesn’t specify the theltem’th pattern in the pattern list, but the 
theltem’th index in the index list. Patterns are numbered from 1. 

procedure Hiliteltem (theltem: integer; 
state: HiliteState); 

void Hiliteltem (short theltem, HiliteState state); 

Hilight the specified item. If. state is hitliteON, this method draws a white 
outline around the box. If state is hiliteOFF, it draws the box normally. 
When state is hiliteDYNAMIC, Hiliteltem flashes the edges of the box. 
Figure 47-1 shows how CPatternGrid highlights items. 

Accessing methods 

procedure GetPattern (var thePattern: Pattern); 
void GetPattern (Pattern *thePattern); 

Return the currently selected pattern in thePattern. The current selection 
is stored in the selection instance variable of the CSelector superclass. 
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Introduction 

CPictFile is a class for reading and writing “draw” files like the kind 
MacDraw produces. 

Heritage 

Superclass 
Subclasses 

Using CPictFile 

You can use this class to read and write files whose type is PICT. These files 
contain “draw” type graphic images made with applications like MacDraw. A 
PICT file begins with 512 bytes of header information followed by a Macin¬ 
tosh picture. 

Since CPictFile inherits its behavior from CFile, you need to use one of 
CFile’s specification methods which file the Open method will open. 

Variables 

Variable Type Description 

header Handle A handle to store the PICT 

header. Used internally. 

Methods 

IPIctFile procedure IPictFile; 

void IPictFile (void); 

Initialize the object. This method calls CFile’s initialization method and allo¬ 
cates memory for the header. 


To learn the details of the 
PICT file format , see Tech- 
Note 27 


CDataFile 

None 
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Free/Dispose 

ReadAII 


WriteAll 


procedure Free; 
void Dispose (void); 

Dispose of the header, then dispose of the object. 

function ReadAII: Handle; 

Handle ReadAII (void); 

Read the picture from the PICT file into contents. You can use the handle 
with Quickdraw routines that expect a PicHandle or you can pass it to 
CPicture’s SetMacPicture method. If there is an error reading the file, this 
method returns NIL. 

procedure WriteAll (contents: Handle); 
void WriteAll (Handle contents); 

Write a picture to a PICT file. The contents handle should be a PicHandle. 


356 Object-Oriented Programming 



CPicture t 
49 


Introduction 

CPicture lets you display Macintosh pictures. The pictures are not editable. 

Heritage 

Superclass 
Subclasses 

Using CPicture 

Use CPicture when you want to display a Macintosh picture. You can display 
the picture in a scroll frame or you can scale it to fit its frame. The picture is 
not editable. The picture is a standard Macintosh picture and is stored in an 
instance variable. You can look at the source code for this class to learn how 
to create your own panorama subclasses. 

Variables 

Variable Type 

macPicture PicHandle 

scaled Boolean 

isResPicture Boolean 
ownsPicture Boolean 


Description 

Handle to the QuickDraw 
picture. 

TRUE if picture is scaled to 
fit in frame. 

TRUE if picture is read 
from a resource. 

TRUE if this object should 
release memory for the 
picture when the object is 
destroyed. 


CPanorama 

None 
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I Picture 


IViewRes 


IVIewTemp 


Free/Dispose 


Methods 

Construction/Destruction 

procedure IPicture (anEnclosure: CView; 
aSupervisor: CBureaucrat; 
aWidth, aHeight: integer; 
aHEncl, aVEncl: integer; 
aHSizing, aVSizing: SizingOption); 

void IPicture (CView *anEnclosure, 

CBureaucrat *aSupervisor, 
short aWidth, short aHeight, 
short aHEncl, short aVEncl, 

SizingOption aHSizing, SizingOption aVSizing); 
Initialize a picture. The arguments are identical to pane initialization. 


Note 

The descriptions of the other arguments are in CPane on 
page 321. 


procedure IViewRes (rType: ResType; resID: integer; 
anEnclosure: CView; aSupervisor: CBureaucrat); 

void IViewRes (ResType rType, short res ID, 

CView *anEnclosure, CBureaucrat *aSupervisor); 

Initialize a picture from a resource template. RType is the resource type for 
the CView subclass you want to initialize. Res ID is the resource ID of the re¬ 
source. AnEnclosure and aSupervisor are the same as for IPicture. 
This method is inherited from CView. 

To initialize a picture from a resource file, use a ' PctP ' resource. 

procedure IViewTemp (anEnclosure: CView; 

aSupervisor: CBureaucrat; viewData: Ptr); 

void IViewTemp (CView ^anEnclosure, 

CBureaucrat *aSupervisor, Ptr viewData); 

This method is used internally for initializing from a resource template. Each 
subclass of CView overrides this method to use its own resource template. 

procedure Free; 
void Dispose (void); 

Dispose of this object. If the object owns the picture (ownsPicture is 
TRUE) the memory for the picture is released. If the picture comes from a re¬ 
source (isResPicture is TRE), this method uses HPurge to purge the 
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Draw 


SetMacPicture 


UsePICT 


GetMacPicture 


SetScaled 


GetScaled 


ResizeFrame 


--- ♦ 

* PICT * resource. If the picture is not from a resource, this method uses 
KillPicture to dispose of the picture. 

Appearance methods 

procedure Draw (var area: Rect); 
void Draw (Rect *area); 

Draw the picture. This method ignores the area parameter. 

Accessing methods 

procedure SetMacPicture (aMacPicture: PicHandle); 
void SetMacPicture (PicHandle aMacPicture); 

Use aMacPicture as the Macintosh picture for this object. If the picture 
comes from a resource, and the resource is purgeable, this method sets 
ownsPicture to FALSE. If the picture does not come from a resource, the 
picture is set to be unpurgeable, and ownsPicture is set to TRUE. 

procedure UsePICT (PICTid: integer); 
void UsePICT (short PICTid); 

Use the 'PICT' resource with ID PICTid as the Macintosh picture for this 
object. This method gets the resource and then callse SetMacPicture. 

function GetMacPicture: PicHandle; 

PicHandle GetMacPicture (void); 

Return a handle to the Macintosh picture. 

Calibration methods 

procedure SetScaled (aScaled: Boolean); 
void SetScaled (Boolean aScaled); 

If aScaled is TRUE, the picture will be scaled to fit its frame. 

function GetScaled: Boolean; 

Boolean GetScaled (void); 

Return TRUE if the picture is scaled. 

procedure ResizeFrame (delta: Rect); 
void ResizeFrame (Rect *delta); 

Resize the picture’s frame by the amount specified. 
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FrameToBounds 


procedure FrameToBounds; 
void FrameToBounds (void); 

Make the frame of the picture the same size as the bounds. 
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50 


To learn the details of the 
PNTG file format, see Tech- 
Note 86 


IPNTGFile 


Introduction 

CPNTGFile is a class for reading and writing “paint” files like the kind Mac¬ 
Paint produces. 

Heritage 

Superclass CDataFile 

Subclasses None 

Using CPNTGFile 

You can use this class to read and write files whose type is PNTG. These files 
contain “paint” or bitmapped graphic images made with applications like 
MacPaint. A PNTG file begins with 512 bytes of header information followed 
by a packed bitmap of the image. 

Since CPNTGFile inherits its behavior from CFile, you need to use one of 
CFile’s specification methods which file the Open method will open. 

The reading and writing methods of this class use objects of class CBitMap. 
That class gives you an object-oriented way to work with Macintosh bit¬ 
maps. 

Variables 

Variable Type Description 

header Handle A handle to store the PNTG 

header. Used internally. 

Methods 

procedure IPNTGFile; 
void IPNTGFile (void); 

Initialize the object. This method calls CFile’s initialization method and allo¬ 
cates memory for the header. 


Object-Oriented Programming 3 6 7 



SO CPNTGFile 


Free/Dispose 


ReadNewBitMap 


WriteBitMap 


procedure Free; 
void Dispose (void); 

Dispose of the header, then dispose of the object. 

function ReadNewBitMap (makePort: Boolean): CBitMap; 
CBitMap *ReadNewBitMap (Boolean makePort); 

Create a new object of class CBitMap and read the contents of this PNTG file 
into it. The makePort parameter is passed to CBitMap’s IBitMap method. 
If it’s true, IBitMap creates a Quickdraw grafport. If there was an error 
reading the image, this method returns NIL. 

Note that this method creates a new bitmap every time you call it. The image 
is not stored in an instance variable. 

procedure WriteBitMap (theBitMap: CBitMap); 
void WriteBitMap (CBitMap *theBitMap); 

Write an object of class CBitMap to a PNTG file. 
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SI 


Horizontal 

strip 


Introduction 

CPrinter is a class that handles standard Macintosh printing dialogs and calls 
the appropriate Print Manager routines. 

Heritage 

Superclass CObject 

Subclasses None 

Using CPrinter 

The printer object manages communication between a document and the 
Macintosh print manager. Every document object can have a printer object 
associated with it. The document’s PrintPageOf Doc method is the meth¬ 
od that actually does the printing. 


If your document is long, you may need to paginate your document (that is, 
divide it into pages). CPrinter lets you split your document into strips, each 
of which is a row or column of pages. At the intersection of a vertical strip 
and a horizontal strip, there is a page. Figure 51-1 shows how you might 
paginate graphic and text documents. 



t 

Vertical strip 

Figure 51-1 Paginating graphic and text documents 
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Note that strips don’t have to be all the same size. Also, notice that each strip 
has a number. You need this number if you set the size or position of each 
strip individually. 

CPrinter lets you set the size and position of strips in a variety of ways. Here 
are a few: 

• To make all pages exactly the size the user chose in the Page 
Setup... dialog, use SetStrips on page 366. 

• To insert a page break at a specific place in a document, use 
SetHorizPageBreak and SetVertPageBreak on page 367. 

• To make all pages the same height or width, use 
SetAllStripWidths or SetAllStripHeights on page 
367. 

• To make a specific strip a specific height or width, use 
SetStripWidth or SetStripHeight on page 367. 

If your document has more than one horizontal and vertical strip, you can 
choose the order the pages print in: horizontally (left to right first) or verti¬ 
cally (top to bottom first), as shown in Figure 51-2. Just send the printer the 
SetPrintDir message with either printHoriz orprintVert as the ar¬ 
gument. 




Figure 51-2 Printing horizontally and vertically 

If you like, you can store a Macintosh print record with your document to 
preserve defaults. You can pass a handle to this record to the IPrinter 
method when you initialize your document. For methods in this class that re¬ 
turn a Boolean value, TRUE means that the printer record stored with the 
printer object has changed. Ordinarily, you won’t need to create a subclass 
of this class. 
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IPrinter 


♦ 


Variables 

Variable 

Type 

Description 

itsDocument 

CDocument 

Document using this 

macTPrint 

THPrint 

Printer. 

Toolbox print 

printDirection 

tPrintDirection 

record. 

The direction of 

printMgrOpen 

Boolean 

printing when there 
is more than one 
strip. 

TRUE, if the Print 

printDocOpen 

Boolean 

Manager is open. 
TRUE, if this printer 

printPageOpen 

Boolean 

is currently printing 
the document. 

TRUE, if this printer 

savedResFile 

integer 

is currently printing 
a page. 

The resource file that 

itsStripWidths 

CRunArray 

this application used 
before CPrinter 
opened the Print 
Manager. 

List of strip widths. 

itsStripHeights 

CRunArray 

List of strip heights. 


Methods 

Construction and destruction methods 

function IPrinter (aDocument: CDocument; 
aMacTPrint: THPrint): Boolean; 

Boolean IPrinter (CDocument *aDocument, 

THPrint aMacTPrint); 

Initialize a printer object. ADocument is the document the printer object is 
associated with. AMacTPrint is a Macintosh print record handle. If 
aMacTPrint is NIL, this method creates a new print record. This method 
returns TRUE if it had to update the aMacTPrint record because it was in¬ 
compatible. The document’s initialization method initializes a printer object 
automatically if the printable parameter to IDocument is TRUE. 
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Free/Dlspose 

OpenPrlntMgr 


ClosePrlntMgr 

SetPrlntDir 

HavePagination 

ResetPagination 

SetStrips 


procedure Free; 
void Dispose (void); 

Dispose of a printer object. 

Accessing methods 

function OpenPrintMgr (fCheckFailure: Boolean): 
Boolean; 

Boolean OpenPrintMgr (Boolean fCheckFailure); 

Open the Print Manager to get ready to print. If fCheckFailure is TRUE 
and this method could not open the Print Manager, this method displays an 
alert telling the user to choose a printer with the Chooser and returns FALSE. 
This method returns TRUE if there was no error or if fCheckFailure is 
FALSE. 

procedure ClosePrintMgr; 
void ClosePrintMgr (void) 

Close the Print Manager. This method aborts the printing of the current page 
and document, if this printer is in the middle of printing. 

procedure SetPrintDir (aPrintDir: tPrintDirection); 
void SetPrintDir (tPrintDirection aPrintDir); 

Set the direction of printing, in case there is more than one horizontal and 
vertical strip. TPrintDirection can be printHoriz or print Vert. 

function HavePagination: Boolean; 

Boolean HavePagination (void) 

Return TRUE if this printer has any pagination information. 

procedure ResetPagination; 
void ResetPagination (void) 

Clear the current pagination, setting the number of horizontal and vertical 
strips to zero. 

procedure SetStrips (numHStrips, numVStrips: integer); 
void SetStrips (short numHStrips, short numVStrips); 

Clear the current pagination and initialize it. This method sets the number of 
strips to numHStrips and numVStrips and sets the width (or height) of 
each strip to the width (or height) of the page size set in Page Setup..., 
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SetHorizPageBreak 


SetVertPageBreak 


SetAIIStrlpWldths 


SetAIIStripHeights 


SetStrlpWldth 


SetStripHeight 


CetStripCount 


Methods 

-- 4 

procedure SetHorizPageBreak (vStripNum: integer, 
hPos: longint); 

void SetHorizPageBreak (short vStripNum, long hPos); 

Set a horizontal page break. VStripNum is the strip you’re changing. HPos 
is the location of the page break in the frame coordinates of this printer’s 
document. 

procedure SetVertPageBreak (hStripNum: integer, 
vPos: longint); 

void SetVertPageBreak.(short hStripNum, long vPos); 

Set a vertical page break. HStripNum is the strip you’re changing. VPos is 
the location of the page break in the frame coordinates of this printer’s doc¬ 
ument. 

procedure SetAllStripWidths (aStripWidth: integer); 
void SetAllStripWidths (short aStripWidth); 

Sets the width all vertical page strips to aStripWidth. 

procedure SetAIIStripHeights (aStripHeight: integer); 
void SetAIIStripHeights (short aStripHeight); 

Sets the height all horizontal page strips to aStripHeight. 

procedure SetStripWidth (pageNum, aStripWidth: 
integer); 

void SetStripWidth (short pageNum, short aStripWidth) 
Sets the width of the vertical strip pageNum to aStripWidth. 

procedure SetStripHeight (pageNum, aStripHeight: 
integer); 

void SetStripHeight (short pageNum, 
short aStripHeight) 

Sets the height of the horizontal strip pageNum to aStripheight. 

procedure GetStripCount (var hStrips, vStrips: 
integer); 

void GetStripCount (short *hStrips, short *vStrips); 
Get the number of horizontal and vertical page strips. 
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PageNumToStrips 

GetPageStart 

GetPageArea 

GetPrintRecord 

GetPagelnfo 


DoPageSetup 


DoPrint 


procedure PageNumToStrips (pageNum: integer; 
var hStrip, vStrip: integer); 

void PageNumToStrips (short pageNum, short *hStrip, 
short *vStrip) 

Get the horizontal and vertical strips that page pageNum falls in. 

procedure GetPageStart (pageNum: integer; 
var startPos: LongPt); 

void GetPageStart (short pageNum, LongPt *startPos) 

Get the starting position of page pageNum in the frame coordinates of this 
printer’s document 

procedure GetPageArea (pageNum: integer; 
var pageArea: LongRect); 

void GetPageArea (short pageNum, LongRect *pageArea) 
Get the area of page pageNum. 

function GetPrintRecord: THPrint; 

THPrint GetPrintRecord (void); 

Return the Toolbox print record. This method calls PrValidate to update the 
record. You should treat the value that this method returns as read-only. 

procedure GetPagelnfo (var paperRect, pageRect: 

Rect; var hRes, vRes: integer); 

void GetPagelnfo (Rect *paperRect, Rect *pageRect, 
short *hRes, short *vRes); 

Get information about the paper size and printable area of the page. The 
paperRect and pageRect are specified in dots. HRes and vRes specify 
the number of dots per inch. 

function DoPageSetup: Boolean; 

Boolean DoPageSetup (void); 

Respond to a Page Setup... menu command. This method displays the stan¬ 
dard job setup dialog, and returns TRUE if you made changes and pressed 
the OK button. 

Printing methods 

procedure DoPrint; 
void DoPrint (void); 

Respond to a Print... menu command. This method displays the standard 
print job dialog. If you click on the OK button, this method sends a 
PrintPageRange message. 
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♦ 


PrintPageRange 


procedure PrintPageRange (firstPage, lastPage: 
integer); 

void PrintPageRange (short firstPage, short lastPage); 

Print the specified range of the document associated with this printer object. 
The DoPrint method usually sends this message. Your application can by¬ 
pass the print dialogs and send this message directly, but Tech Note 122 dis¬ 
courages this practice. 

This method sends your document an About ToPr in t message to give it an 
opportunity to adjust the page range. Then, for each page in the page range, 
it sends your document a PrintPageofDoc message. 
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52 


Introduction 

CRadioControl implements a standard Macintosh radio button. 


Note 

Earlier versions of The THINK Class Library used a different 
scheme to handle radio buttons. This class uses the depen¬ 
dent/provider mechanism implemented by CCollaborator 
to work with groups of radio buttons. The older class, CRa- 
dioButton is provided for backward compatibility, but not 
recommended. 


Heritage 

Superclass CButton 

Subclasses None 

Using CRadioControl 

CRadioControl is a class that implements the standard Macintosh radio but¬ 
ton. Since radio buttons always come in groups, a button must be a part of a 
radio group. The class CRadioGroupPane implements radio groups. 

Like any other button, a radio button can have a command associated with 
it. Use the SetClickCmd method to set a radio button’s command. You can 
also use any of the other CControl methods to manipulate the radio button. 

See CRadioGroup pane for a discussion about working with groups of radio 
buttons. 

Variables 

This class has no instance variables. 
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IRadioControl 

INewRadioControl 


DoCoodClick 


Methods 

procedure IRadioControl (CNTLid: integer; 

anEnclosure: CView; aSupervisor: CBureaucrat); 

void IRadioControl (short CNTLid, CView *anEnclosure, 
CBureaucrat *aSupervisor); 

Initialize a radio button from a CNTL resource. CNTLid is the resource ID 
for the radio button. AnEnclosure is the pane the radio button appears in. 
The enclosure should be a CRadioGroupPane. ASupervisor is the super¬ 
visor of the radio button. The supervisor should be a CRadioGroupPane. 

procedure INewRadioControl (aWidth, aHeight: integer; 
aHEncl, aVEncl: integer; title: StringPtr; 
fVisible: Boolean, anEnclosured: CView, 
aSupervisor: CBureaucrat); 

void INewRadioControl (short aWidth, short aHeight, 
short aHEncl, short aVEncl, StringPtr title. 

Boolean fVisible, CView *anEnclosure, 

CBureaucrat *aSupervisor); 

Initialize a radio button from the parameters in the argument list. AWidth 
and aHeight are the width and height of the button in pixels. AHEncl and 
aVEncl are the horizontal and vertical position of the button within its en¬ 
closure. Title is the text to write beside the button. And if fVisible is 
TRUE, the window is drawn immediately after it’s created 


Note 

The rest of the parameters are described under 
IRadioControl on page 372. 


procedure DoGoodClick (whichPart: integer); 
void DoGoodClick (short whichPart); 

When the user presses and releases the mouse within the radio button, and 
the radio button was off, this method calls SetValue method to turn on the 
radio button. Note that SetValue in CControl sends a Broadcast Change 
message. The ProviderChanged method in CRadioGroupPane takes care 
of turning off the button that was on. 
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Introduction 

CRadioGroupPane is a class that manages a group of radio buttons. 


Note 

Earlier versions of The THINK Class Library used a different 
scheme to handle radio buttons. This class uses the depen¬ 
dent/provider mechanism implemented by CCollaborator 
to work with groups of radio buttons. The older class, CRa- 
dioGroup is provided for backward compatibility, but not 
recommended. 


Heritage 

Superclass CPane 

Subclasses None 

Using CRadioGroupPane 

A radio group pane is a pane specifically designed for grouping radio but¬ 
tons of class CRadioControl. The radio group pane helps you make sure that 
only one radio button in a group is on. The button that is on in a radio group 
is called the station. 

To add a button to a radio group pane, simply use the group as the button’s 
supervisor when you initialize the button. The group pane assumes that all 
its subviews are radio buttons. When a radio button is selected, it sends a 
BroadcastChange message with controlValueChanged as the rea¬ 
son. The group pane turns off the previously selected button and sets 
currentStation to the newly selected button. 

There are two ways you can respond to clicks in radio buttons. One way is 
to give each radio button a unique ID, and to use SetStationIDtoset the 
initial radio button. After that, let the radio group pane manage the radio 
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IRadioGroupPane 


buttons. When you want to find out which button is the station, use 
GetStationID. 

The other way is to give each radio button its own command. Use the 
SetClickCmd method that CRadioControl inherits from CButton to give a 
radio button its own command. When you click on a radio button to turn it 
on, CRadioControl’s DoGoodClick method sends the button’s supervisor a 
DoCommand message. If the radio button’s supervisor is a plain CRadio¬ 
GroupPane, the command should be handled by the group pane’s supervi¬ 
sor. Or you can create a subclass of CRadioGroupPane with a DoCommand 
method to handle clicks in radio buttons. 

Variables 

Only CRadioGroupPane and its subclasses should access this instance vari¬ 
able. In THINK C, this variable is protected. 

Variable Type Description 

currentStation CRadioControl The currently select¬ 

ed radio button 


Methods 

Construction and destruction methods 

procedure IRadioGroupPane (anEnclosure: CView; 
aSupervisor: CBureaucrat; 
aWidth, aHeight: integer; 
aHEncl, aVEncl: integer; 
aHSizing, aVSizing: SizingOption); 

void IRadioGroupPane (CView *anEnclosure, 

CBureaucrat *aSupervisor, 
short aWidth, short aHeight, 
short aHEncl, short aVEncl, 

SizingOption aHSizing, SizingOption aVSizing); 

Initialize a radio group pane. ASupervisor is the bureaucrat that owns the 
radio group pane. Typically, the supervisor is a pane or a window. 


Note 

The descriptions of the other arguments are in CPane on 
page 321. 
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SetStationID 


CetStationID 


ProviderChanged 


♦ 


Accessing methods 

procedure SetStationID (aStationID: longint); 
void SetStationID (long aStationID); 

Change the current selection to the button with the specified ID number. 

function GetStationID: longint; 
long GetStationID (void); 

Return the ID number of the currently selected radio button. Returns 0 if no 
station is selected. 

Change notification method 

procedure ProviderChanged (aProvider: CCollaborator; 
reason: longint; info: Ptr); 

void ProviderChanged (CCollaborator *aProvider, 
long reason, void* info); 

A radio button in this radio group pane has just been selected and sent a 
BroadcastChange message with controlValueChanged as the rea¬ 
son. This method turns off the previously selected button and sets 
currentStationto the newly selected button. 
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To learn about Macintosh 
resources and resource files, 
see Inside Macintosh I\ 
Chapter 5, Inside Macin¬ 
tosh IV, Chapter 3, and 
Tech Note 214. 


IResFile 


CResFile 

54 


Introduction 

CResFile is an abstract class for working with Macintosh resource files. 

Heritage 

Superclass CFile 

Subclasses None 

Using CResFile 

If your application reads and writes resources make a subclass of CResFile 
and give it methods to access the resources. CResFile gives you methods to 
open and close resource files and to make the file the current resource file. 

Since CResFile inherits its behavior from CFile, you need to use one of 
CFile’s specification methods which file the Open method will open. 

Variables 

Variable Type Description 

refNum Integer File system reference num¬ 

ber of opened file 

Methods 

procedure IResFile; 
void IResFile (void); 

Initialize the object. This method calls CFile’s initialization method and ini¬ 
tializes refNum to 0. 
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Open 

Close 

MakeCurrent 

IsOpen 

Update 

HasResFork 

CreateNew 


procedure Open (permission: SignedByte); 
void Open (SignedByte); 

Open the resource file with the specified permission. If the file can’t be 
opened, this method calls FailResError. Remeber that you need use one 
of CFile’s specification methods to specify which file to open. 

procedure Close; 
void Close (void); 

Close this resource file. This method calls FailOSErrif there was a prob¬ 
lem closing the file. 

procedure MakeCurrent; 
void MakeCurrent (void); 

This method makes the resource file the current resource file. 

function IsOpen: Boolean; 

Boolean IsOpen (void); 

Returns TRUE if the resource fork of this file is open. 

procedure Update; 
void Update (void); 

Updates this resource file by writing out the changed resource. 

function HasResFork: Boolean; 

Boolean HasResFork (void); 

Returns TRUE if this file has a resource fork. The file must have been previ¬ 
ously specified. 

procedure CreateNew (creator, fType: OSType); 
void CreateNew (OSType creator, OSType fType) 

Creates a new resource file. If the file already exists but has no resource fork, 
this method gives it a resource fork. 
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Introduction 

CRunArray implements a dynamic array of long integers that can conserve 
space. 

Heritage 

Superclass CArray 

Subclasses None 

Using CRunArray 

CRunArray implements a dynamic array of long integers. It conserves space 
if your array contains lots of sequences of entries with the same value. These 
sequences are called runs. A run array consists of runs, which contain a val¬ 
ue and the number of consecutive entries that have that value. For example, 
Figure 8-1 shows how a traditional array and a run array would store the 
same values. 


Traditional Array 



Run Array 

Run #Entries Value 


1 

2 

3 

64 

1 

45 


Figure 8-1 A traditional array and a run array 

To put an entry into the array, you can choose between SetValue and 
InsertValue. SetValue replaces an entry with a new entry. 

Insert Value inserts a run of values into the array. To delete an entry, use 
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I Run Array 


GetNumltems 


InsertValue 


DeleteValue. To sum a range of entries in the array, use the methods 
SumRange and FindSum. 

When used with a run array, many CArray methods operate on runs of en¬ 
tries, not on individual entries. This table shows you some of those CArray 
methods and gives the CRunArray method you should use instead. 


CArray method 

Get Item 
Setltem 
InsertAtIndex 
Deleteltem 


CRunArray method 

GetValue 
SetValue 
InsertValue 
DeleteValue 


In a CRunArray, the instance variable numltems contains the number of 
runs in the array. To find the number of entries, use the method 
GetNumltems, instead. 

Variables 

Variable Type 

itemCount longint 

hRuns tRunHndl 

Methods 

Creation method 

procedure IRunArray; 
void IRunArray; 

Initialize the array. The number of items and runs is set to 0 (zero). 

Accessing method 

function GetNumltems: longint; 
long GetNumltems (void); 

Return the number of items in the array. 

Insertion and deletion methods 

procedure InsertValue (item, value, count: longint); 
void InsertValue (long item, long value, long count); 

Insert a run of values into the array. Item is the index to start the run at. If 
you specify an index beyond the end of the array, the run is added to the 


Description 

Number of entries in the 
array. 

Handle to runs. Same as 
hltems. 
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SetValue 


DeleteValue 


DeleteAll 


CetValue 


SumRange 


FindSum 


---♦ 

end of the array. Value is the value for all in the entries in this run. Count is 
the length of the run. 

procedure SetValue (index, value: longint); 
void SetValue (long index, long value); 

Set the value of the entry at index to value. 

procedure DeleteValue (index: longint); 
void DeleteValue (long index); 

Delete the entry at index. All the entries following index move up one po¬ 
sition. 

procedure DeleteAll; 
void DeleteAll (void); 

Delete all the entries in this array. 

Membership method 

function GetValue (index: longint): longint; 
long GetValue (long index); 

Return the value of the entry at index. 

Summing methods 

function SumRange (startlndex, endlndex: longint): 
longint; 

long SumRange (long startlndex, long endlndex); 

Return the sum of the items between startlndex and endlndex, inclu¬ 
sive. 

function FindSum (aSum: longint): longint; 
long FindSum (long aSum) ; 

Return the index of the first entry such that all the entries from 1 to that entry 
have a sum equal to or greater than sum. 

Run-handling methods 

CArray uses these methods internally to manipulate runs. You should need 
to use them only if you are creating a subclass of CRun Array. In THINK C, 
they are protected. 


Object-Oriented Programming 381 



^ 55 CRunArray 

FlndRun 


InsertRun 


DeleteRun 


procedure FindRun (itemlndex: longint; 
var runlndex, firstlnRun: longint); 

void FindRun (long itemlndex, long *runlndex, 
long *firstInRun); 

Return the number of the run that contains the entry at itemlndex. This 
method sets runlndex to the run number and firstlnRun to the index 
of the first entry in the run. If itemlndex is not in the array, this method 
sets runlndex and firstlnRun to BAD__INDEX. 

procedure InsertRun (index, runLength, value: 
longint); 

void InsertRun (long index, long runLength, 
long value); 

Insert a new run into the array. Index is the index of the first entry in the 
run. RunLength is the number of entries in the run. Value is the value of 
all the entries in the run. 

procedure DeleteRun (runlndex: longint); 
void DeleteRun (long runlndex); 

Delete the run at number runlndex from the array. 
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56 


CScrollBar implements a standard Macintosh scroll bar. 

Heritage 

Superclass CControl 

Subclasses None 

Using CScrollBar 

This class implements a Macintosh scroll bar. To make scroll bars easier to 
use, this class distinguishes between a mouse click in an indicator (the scroll 
box or the “thumb”) and a click in any other part of the scroll bar. Both be¬ 
haviors are implemented in the DoClick method of the CControl class. 

When you click in any part other than an indicator, the DoClick method 
calls the Toolbox routine TrackControl with an action procedure, or ac¬ 
tion proc. The action procedure is the routine that adjusts what the scroll 
bar controls. In most cases, the scroll bar controls a panorama. To set the ac¬ 
tion proc, use the SetActionProc method inherited from CControl. 

When you click in the indicator, the DoClick method sends a 
DoThumbDragged message to the scroll bar. This method calls a thumb 
function that you provide. The thumb function is the routine that adjusts 
whatever the scroll bar controls. Thumb functions are unique to scroll bars. 
To set the thumb function, use the SetThumbFunc method. 

Usually, you’ll use a scroll bar to control a pane. The class CScrollPane is a 
scrollable pane (a panorama) with one or two scroll bars. The CScrollPane 
class handles the usual cases, so you don’t have to provide an action proc or 
a thumb function. 
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Variables 



Variable 

Type 

Description 

theOrientation 

Orientation 

Which way the 
scroll bar lies, hori¬ 
zontal or vertical. 

theThumbFunc 

ProcPtr 

Function to call after 
a thumb drag. 


Methods 

Construction and destruction methods 

IScrollBar procedure IScrollBar (anEnclosure: CView; 

aSupervisor: CBureaucrat; 
anOrientation: Orientation; 
aLength, aHEncl, aVEncl: integer); 

void IScrollBar (CView *anEnclosure, 

CBureaucrat *aSupervisor, 

Orientation anOrientation, 

short aLength, short aHEncl, short aVEncl); 

Initialize a scroll bar. AnEnclosure is the pane or window the scroll bar 
belongs to. ASupervisor is the scroll bar’s supervisor in the chain of com¬ 
mand. Orientation is either HORIZONTAL or VERTICAL. ALength is the 
length of the scroll bar. AHEncl and aVEncl are the horizontal and vertical 
position of the upper left corner of the scroll bar. 

Accessing methods 

SetThumbFunc procedure SetThumbFunc (aThumbFunc: ProcPtr); 

void SetThumbFunc (VoidFunc aThumbFunc); 

Set aThumbFunc to be the scroll bar’s thumb function. The default 
DoClick method for controls sends a DoThumbDragged message to the 
control when the user moves an indicator in a control. The 
DoThumbDragged method for scroll bars calls the thumb function. You 
should declare a Pascal thumb function like this: 

procedure MyThumbFunc (theControl: CControl; 
delta: integer); 

And you should declare a C thumb function like this: 

void MyThumbFunc (CControl *theControl, 
short delta); 
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Methods 


Draw 


Activate 


Deactivate 


DoClick 


DoThumbDragged 


-—- ♦ 

TheCont rol is the control whose indicator was moved Delta is the 
amount by which the value changed. To get the current value of the control, 
you can send it a Get Value message. 

Drawing methods 

procedure Draw (var area: Rect); 
void Draw (Rect *area); 

Draw the scroll bar. If the scroll bar is active, this method draws it the normal 
way. If the scroll bar is inactive, this method draws only the frame of the 
scroll bar. 

procedure Activate; 
void Activate (void); 

Activate the scroll bar. 

procedure Deactivate; 
void Deactivate (void); 

Deactivate the scroll bar. 

Click response methods 

procedure DoClick (hitPt: Point; 

modifierKeys: integer; when: longint); 

void DoClick (Point hitPt, short modifierKeys, 
long when); 

Handle a click in the scroll bar. If the scroll bar’s enclosure is a scroll pane, 
send an Ad justScrollMax message to the scroll pane. 

procedure DoThumbDragged (delta: integer); 
void DoThumbDragged (short delta); 

If the scroll bar has a thumb function associated with it, call it with the scroll 
bar and delta as arguments. The default DoClick method for controls 
sends a DoThumbDragged message to the control when the user moves an 
indicator in a control. See SetThumbFunc on page 384. 
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57 


Introduction 

CScrollPane implements a pane with scroll bars that control a panorama. 

Heritage 

Superclass CPane 

Subclasses None 

Using CScrollPane 

A scroll pane is a pane with a panorama and scroll bars to control what is be¬ 
ing displayed in the pane. Most of your applications will use a scroll pane 
that occupies most of the window. After creating a scroll pane, you can send 
it a FitToEnclFrame message to make it as big as the window. 

All you have to do to use a scroll pane is install a panorama with the 
InstallPanorama method. The scroll pane uses the scale of the panora¬ 
ma for the values of the scroll bars. 

The scroll bars and panorama do not communicate directly. Mouse clicks in 
the scroll bars are reported to the scroll pane, which then tells the panorama 
how to scroll or shift its image. Similarly, changes in the panorama which 
would affect the scroll bars are reported to the scroll pane, which then ad¬ 
justs the scroll bars. 
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Variables 



Variable 

Type 

Description 

itsPanorama 

CPanorama 

The scrollable view. The 
“content” of the scroll 
pane. 

itsHorizSBar 

CScrollBar 

The scroll pane’s horizon¬ 
tal scroll bar. 

itsVertSBar 

CScrollBar 

The scroll pane’s vertical 
scroll bar. 

itsSizeBox 

CSizeBox 

The scroll pane’s size box. 

hExtent 

longint 

For internal use. 

vExtent 

longint 

For internal use. 

hUnit 

integer 

For internal use. 

vUnit 

integer 

For internal use. 

hSpan 

integer 

For internal use. 

vSpan 

integer 

For internal use. 

hStep 

integer 

Number of horizontal 
units to scroll by when the 
user clicks on an arrow. 

vStep 

integer 

Number of vertical units to 
scroll by when the user 
clicks on an arrow. 

hOverlap 

integer 

Number of units to overlap 
when the user clicks in a 
page region. 

vOverlap 

integer 

Number of units to overlap 
when the user clicks in a 
page region. 


Methods 

Construction and destruction methods 

IScrollPane procedure IScrollPane (anEnclosure: CView; 

aSupervisor: CBureaucrat; 

aWidth, aHeight, aHEncl, aVEncl: integer; 
aHSizing, aVSizing: SizingOption; 
hasHoriz, hasVert, hasSizeBox: Boolean) 

void IScrollPane (CView *anEnclosure, 

CBureaucrat *aSupervisor, 
short aWidth, short aHeight, 
short aHEncl, short aVEncl, 

SizingOption aHSizing, SizingOption aVSizing, 
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IViewRes 


IVIewTemp 


InstallPanorama 


SetSteps 


♦ 


Boolean hasHoriz, Boolean hasVert, 

Boolean hasSizeBox); 

Initialize a scroll pane. All but the last three arguments are identical to the ar¬ 
guments to IPane. If hasHoriz is TRUE, the scroll pane has an horizontal 
scroll bar. If hasVert is TRUE, the scroll pane has a vertical scroll bar. If 
hasSizeBox is TRUE, the scroll pane draws a size box in the lower-right 
corner of the pane. 


Note 

The descriptions of the other arguments are in CPane on 
page 321. 


procedure IViewRes (rType: ResType; resID: integer; 
anEnclosure: CView; aSupervisor: CBureaucrat); 

void IViewRes (ResType rType, short resID, 

CView *anEnclosure, CBureaucrat *aSupervisor); 

Initialize a scroll pane from a resource template. RTtype is the resource 
type for the CView subclass you want to initialize. Res ID is the resource ID 
of the resource. AnEnclosure and aSupervisor are the same as for 
IScrollPane. This method is inherited from CView. 

To initialize a scroll pane from a resource file, use a ' ScPn' resource. 

procedure IViewTemp (anEnclosure: CView; 

aSupervisor: CBureaucrat; viewData: Ptr); 

void IViewTemp (CView *anEnclosure, 

CBureaucrat *aSupervisor, Ptr viewData); 

This method is used internally for initializing from a resource template. Each 
subclass of CView overrides this method to use its own resource template. 

Accessing methods 

procedure InstallPanorama (aPanorama: CPanorama); 
void InstallPanorama (CPanorama *aPanorama); 

Establish aPanorama as the panorama associated with this scroll pane. This 
method sends AdjustScrollMax and Calibrate messages to the scroll 
pane. 

procedure SetSteps (aHStep, aVStep: integer); 
void SetSteps (short aHStep, short aVStep); 

Set the amount to scroll when the user clicks on the arrows of a scroll bar. 
The units are in the panorama’s units. 
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CetSteps 


SetOverlaps 


Getlnterior 


AdjustScrollMax 


Calibrate 


ChangeSize 


DoHorizScroll 


procedure GetSteps (var theHStep, theVStep: integer); 
void GetSteps (short *theHStep, short *theVStep); 

Get the amount to scroll when the user clicks on the arrows of a scroll bar. 
The units are in the panorama’s units. 

procedure SetOverlaps (aHOverlap, aVOverlap: integer); 
void SetOverlaps (short aHOverlap, short aVOverlap); 
Set the amount of overlap when the user clicks in the page (gray) regions of 
the scroll bar. The units are in the panorama’s units. 

procedure Getlnterior (var thelnterior: LongRect); 
void Getlnterior (LongRect *theInterior); 

Get the interior of the scroll pane. The interior excludes the space that the 
scroll bars occupy. 

Scroll bar maintenance methods 

procedure AdjustScrollMax; 
void AdjustScrollMax (void); 

Adjust the maximum value of the scroll bars from the extent and frame size 
of the panorama. 

procedure Calibrate; 
void Calibrate (void); 

Adjust the scroll bar’s thumb when the position of the frame of the panora¬ 
ma changes. 

procedure ChangeSize (delta: Rect; redraw: Boolean); 
void ChangeSize (Rect *delta. Boolean redraw); 

Change the size of a scroll pane. Each component of the delta rectangle 
specifies how each side will change. Positive values mean down and to the 
right. Negative values mean up and to the left. If redraw is true, the scroll 
pane is redrawn on the next update event. 

Scroll performance methods 

procedure DoHorizScroll (whichPart: integer); 
void DoHorizScroll (short whichPart); 

Scroll horizontally. WhichPart specifies which part of the scroll bar was 
hit. This method sends aDoScroll message. 
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♦ 


DoVertScroll 


DoThumbDrag 


DoScroll 


SBarActlonProc 


SBarThumbFunc 


procedure DoVertScroll (whichPart: integer); 
void DoVertScroll (short whichPart); 

Scroll vertically. WhichPart specifies which part of the scroll bar was hit. 
This method sends a DoScroll message. 

procedure DoThumbDrag (hDelta, vDelta: integer); 
void DoThumbDrag (short hDelta, short vDelta); 

Adjust the panorama when the scroll box (thumb) has been dragged. This 
method sends a DoScroll message to the panorama. 

procedure DoScroll (hDelta, vDelta: longint); 
void DoScroll (long hDelta, long vDelta); 

Scroll the panorama belonging to this pane by hDelta units horizontally 
and vDelta units vertically. The units are given in the panorama’s coordi¬ 
nates. All the other methods in this class call this method to handle scrolling. 

Functions 

Note that these are procedures, not methods. 

procedure SBarActionProc (macControl: ControlHandle; 
whichPart: integer); 

pascal void SBarActionProc (ControlHandle 
macControl, short whichPart); 

The Toolbox TrackControl routine calls this function continuously while 
the mouse is down in any part of the scroll bar except the scroll box 
(thumb). This function sends the scroll bar’s supervisor (the scroll pane) 
DoHorizScroll and DoVertScroll messages that actually scroll the 
panorama. 

procedure SBarThumbFunc (theSBar: CScrollBar; 
delta: integer); 

void SBarThumbFunc (CScrollBar *theSBar, short delta); 

The scroll bar’s DoThumbDragged method calls this routine after the scroll 
box of a scroll bar has been moved. A control’s DoClick method sends a 
DoThumbD ragged message when the user moves the indicator of a control. 
This function sends the scroll bar’s supervisor (the scroll pane) a 
DoThumbDrag message. 
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Introduction 

CSelector is an abstract class for drawing panes with several items that users 
can choose from. A tool palette is an example of a selector. 

Heritage 

Superclass CPanorama 

Subclasses CGridSelector 

Using CSelector 

CSelector is an abstract class that defines the basic behavior of a pane that 
lets you choose from several items. A good example of a selector is a tool 
palette or a pattern palette. The THINK Class Library includes CGridSelector, 
which is a class for implementing those kinds of palettes, and its descen¬ 
dants CPatternGrid, for displaying the standard patterns, and CCharGrid, for 
displaying characters in a grid. You can use these classes directly for pattern 
palettes and tool palettes. If you want to implement a different kind of selec¬ 
tor, you’ll need to create a subclass of CSelector. 

A selector works like menu without command numbers. Each selector has a 
command base, which is like a menu ID. You set the command base when 
you create a selector, or you can set it once it’s been created. A selector con¬ 
tains items. You specify the number of items when you create the selector. 

Every selector needs to have a Draw method to display the items. How the 
items appear in the selector and how they’re arranged is up to you. You will 
also need to override the Findltem method to determine which item you 
clicked on, and you’ll need to override the Hiliteltem method highlight 
the selected item. If you want your selector to respond to double-click’s 
you’ll need to override the DoDoubleClick method as well. 
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ISelector 


Variables 


Variable 

Type 

numlterns 

integer 

selection 

integer 

commandBase 

integer 


Description 

The number of items to 
choose from. 

The currently selected 
item. 

The base value for con¬ 
verting selections into 
command numbers. 


Methods 

Construction and destruction methods 

procedure ISelector (anEnclosure: CView; 
aSupervisor: CBureaucrat; 
aWidth, aHeight: integer; 
aHEncl, aVEncl: integer; 
aHSizing, aVSizing: SizingOption; 
aNumltems, aSelection, aComraandBase: integer); 

void ISelector (CView *anEnclosure, 

CBureaucrat *aSupervisor, 
short aWidth, short aHeight, 
short aHEncl, short aVEncl, 

SizingOption aHSizing, SizingOption aVSizing, 
short aNumltems, short aSelection, 
short aCommandBase); 

Initialize a selector. The first eight arguments to this routine are identical to 

the ones for IPane. 


ANumltems specifies the number of items in this selector. ASelection is 
the initial item. ACommandBase is the base value for converting the selected 
item into a command number. 


Note 

The descriptions of the other arguments are in CPane on 
page 321. 
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DoClick 


HItSamePart 


ChangeSelection 


♦ 


Mouse methods 

procedure DoClick (hitPt: Point; 

modifierKeys: integer; when: longint); 

void DoClick (Point hitPt, short modifierKeys, 
long when); 

This method converts a click into a command number and sends it to the 
selector’s supervisor in a DoCommand message. DoClick sends the 
selector a Findltem message to find out which item got the click. 


Once it has an items, DoClick uses the same scheme as CBartender to 
build a command number.. It puts the command base in the high word of a 
long integer, the item number in the low word, and negates the resulting 
long integer. 


- 


commandBase 


itemHit 


Figure 58-1 How DoClick builds the command number. 


If the new selection is not the same as the current selection, this method 
sends a ChangeHilite message to the selector. If the new selection is the 
same as the current selection, and there was a double-click, this method 
sendsa DoDoubleClick message to the selector. 

Since most of the work is done in methods the you must override, your CSe- 
lector subclass shouldn’t need to override this method. You might want to 
override this method to handle things like triple-clicks. 

function HitSamePart (pointA, pointB: Point): Boolean; 
Boolean HitSamePart (Point pointA, Point pointB); 

Returns TRUE if the mouse went down in the same item, FALSE otherwise. 
The default method checks to see if Findltem (pointA) and Find- 
Item (pointB) return the same item. Your CSelector subclass should not 
need to override this method. 

Accessing methods 

procedure ChangeSelection (aSelection: integer); 
void ChangeSelection (short aSelection); 

Changes the selection from the current selection to aSelection. If 
aSelection is not the same as the current selection, this method turns off 
the highlighting of the current selection and turns on the highlighting of the 
new selection. Your subclass should not need to override this method. 
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CetSelection 

SetCommandBase 

GetCommandBase 

Hiliteltem 


Findltem 


function GetSelection: integer; 
short GetSelection (void); 

Return the current selection. You shouldn’t need to override this method. 

procedure SetCommandBase (aCommandBase: integer); 
void SetCommandBase (short aCommandBase); 

This method sets the selector’s command base. CSelector uses the command 
base to build a command number from the item hit. Your subclass should 
not need to override this method. 


function GetCommandBase: integer; 
short GetCommandBase (void); 

Return the value of the selector’s command base. Your subclass should not 
need to override this method. 


procedure Hiliteltem (theltem: integer; 
state: HiliteState); 

void Hiliteltem (short theltem, HiliteState state); 
Hilight the specified item. Hiliteltem can take on of three values for the 
state parameter: 


Hilite state value 

hiliteOFF 

hiliteON 

hiliteDYNAMIC 


Behavior 

Turn highlighting off for the item. 

Turn highlighting on for the item. 

Flash the selected item without selecting 
or deselecting. 


It’s up to you how you highlight the items of your selector. In most cases, it’s 
sufficient to invert the rectangle that encloses the specified item. When high¬ 
lighting is on, the item should be inverted. When highlighting is off, the item 
should appear normally. Dynamic highlighting is used when the selector is 
used as a menu. See the CSelectorMDEF class. 


function Findltem (hitPt: Point): integer; 
short Findltem (Point hitPt); 

Determine which item corresponds to a mouse down at a specified point. 
It’s up to you how your selector arranges and displays its items. Typically, 
items are arranged in a grid or a table. Your subclass must override this 
method. 
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DoDoubleCIIck 
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procedure DoDoubleClick; 
void DoDoubleClick (void); 

Respond to a double-click. The first click will have set the selection, so the 
double-click will pertain to that item. If your selector subclass responds to 
double-clicks, you should override this method. 
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ISelectorMDEF 


Introduction 

CSelectorMDEF is a class that lets you use descendants of CSelector as cus¬ 
tom menus. 

Heritage 

Superclass CPaneMDEF 

Subclasses None 

Using CSelectorMDEF 

CSelectorMDEF is a class that handles menu selection for custom menus 
based on CSelector panes. If you pass CSelectorMDEF’s initialization method 
a descendant of CSelector, you’ll be able to use it as a custom menu. CSelec¬ 
torMDEF’s Chooseltem method takes care of selecting items from the CSe¬ 
lector. If you pass ISelectorMDEF a descendant of CTearOffMenu, you 
can use your custom menu as a tear-off menu. 

Variables 

This class has no instance variables. 

Methods 

Construction and destruction methods 

procedure ISelectorMDEF (MDEFid: integer; 

aPane: CPane; aTearOffMenu: CTearOffMenu); 

void ISelectorMDEF (short MDEFid, CPane *aPane, 
CTearOffMenu *aTearOffMenu); 

Initialize the selector MDEF. This method passes the arguments to 
CPaneMDEF’s initialization method. APane must be a selector pane de¬ 
scended from CSelector. CTearOffMenu should be a descendant of 
CTearOffMenu where the custom menu will be displayed when it’s torn off. 
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Chooseltem 


procedure Chooseltem (macMenu: MenuHandle; 
menuRect: Rect; hitPt: Point; 
var whichltem: integer); 

void Chooseltem (MenuHandle macMenu, Rect *menuRect, 
Point hitPt, short *whichltem); 

This method handles menu selection for custom menus. 

If the hitPt is within the menuRect, this method sets up the QuickDraw 
drawing environment to match the pane’s drawing environment. The Quick¬ 
Draw origin is set so the point (0, 0) is the top left of the pane. Chooseltem 
then sends a Findltem message to the pane associated with this object. 


400 Object-Oriented Programming 



CSizeBox » 
60 


ISizeBox 


Introduction 

CSizeBox implements a Macintosh grow icon. 

Heritage 

Superclass CPane 

Subclasses None 

Using CSizeBox 

In most cases, you will not need to use this class yourself. It is used by 
CScrollPane to draw a Macintosh grow icon at the lower left corner of any 
pane, not just in the lower right corner of a window. 

The first version of the THINK Class Library used an 'SICN' resource to draw 
the grow icon. If the useSICN flag is TRUE, the Draw method uses the re¬ 
source, otherwise it calls the Toolbox routine DrawGrowIcon. 

Variables 

Variable Type Description 

useSICN Boolean TRUE, if this size box uses 

a SICN resource instead of 
calling DrawGrowIcon. 

Methods 

Construction and destruction methods 

procedure ISizeBox (anEnclosure: CView; 
aSupervisor: CBureaucrat); 

void ISizeBox (CView *anEnclosure, 

CBureaucrat *aSupervisor); 

Initialize a size box. This method places a pane containing a size box at the 
lower right of its enclosure. The sizing options for a size box are 
sizFIXEDRIGHT and sizFIXEDBOTTOM. By default, useSICN is FALSE. 
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Free/Dispose 


Draw 


Activate 


Deactivate 


procedure Free; 
void Dispose (void); 

Dispose of a size box. 

Appearance methods 

procedure Draw (var area: Rect); 
void Draw (Rect *area); 

Draw a size box. If the pane is active, this method draws the size box. If the 
pane is inactive, this method draws a white rectangle. If useSICN is FALSE, 
this method uses the Toolbox’s grow icon, otherwise it uses a ' SICN' re¬ 
source to draw the grow icon. 

procedure Activate; 
void Activate (void); 

The enclosure the size box belongs to is becoming active. The default meth¬ 
od sends a Draw message to the size box 

procedure Deactivate; 
void Deactivate (void); 

The enclosure the size box belongs to is becoming inactive. The default 
method sends a Draw message to the size box. 

Class resources 

If useS ICN is TRUE, this class uses an ' SICN' resource to draw the grow 
icon. 

Resource Description 

SICN 2 00 The grow icon 
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Push 


Pop 


CStack t 
61 


Introduction 

CStack implements a stack of objects. 

Heritage 

Superclass CCluster 

Subclasses None 

Using CList 

Use an object of class CStack when you need to maintain a stack of objects. 
You can use the iteration methods that CStack inherits from CCluster to ap¬ 
ply functions to each item in the stack, 

Variables 

This class has no instance variables. 

Methods 

procedure IStack; 
void IStack (void); 

Initialize the stack. This method calls the CCluster’s initialization method. 

procedure Push (theObect: CObject); 
void Push (CObject *theObject); 

Push theObject on the stack. 

function Pop : CObject; 

CObject *Pop; 

Pop the item from the top of the stack. If the stack is empty, this method re¬ 
turns NIL. 
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CSwitchboard 

62 


Introduction 

CSwitchboard is the class that processes Macintosh Toolbox events and 
sends the appropriate messages to objects in the THINK Class Library. There 
is normally only one instance of this class. 

Heritage 

Superclass CObject 

Subclasses None 

Using CSwitchboard 

The single instance of this class handles all the Macintosh Toolbox events 
and sends messages to objects. The application’s Run method repeatedly 
sends ProcessEvent messages to this object to dispatch messages to the 
objects that make up your application. 

The application initialization method I Application creates the single in¬ 
stance of CSwitchboard. The switchboard is stored in the application’s 
itsSwitchboard instance variable. 


Note 

You need to subclass CSwitchboard only if your application 
handles applEvt, app2Evt, or app3Evt events. Then 
you should override the DoOtherEvent method. 


Variables 

mouseRgn RgnHandle 


Argument for 
WaitNextEvent to han¬ 
dle cursor adjustment. 
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ISwitchboard 


DoMouseDown 


DoMouseUp 


DoKeyEvent 


DoDiskEvent 


Methods 

Initialization methods 

procedure ISwitchboard; 
void ISwitchboard (void); 

Initialize the switchboard The application’s I Application method cre¬ 
ates the switchboard and sends it this message. This method also installs one 
handler for all AppleEvents. The handler sends the switchboard a 
DoAppleEvent message. 

Mouse methods 

procedure DoMouseDown (macEvent: EventRecord); 
void DoMouseDown (EventRecord *macEvent); 

The user pressed the mouse button. This method sends a DispatchClick 
message to the desktop, and stores the event in the global 
gLastMouseDown. 

procedure DoMouseUp (macEvent: EventRecord); 
void DoMouseUp (EventRecord *macEvent); 

The user released the mouse button. This message sends a DoMouseUp 
message to the last view hit. Since mouse ups always follow a mouse down, 
it’s not important where the mouse came up, but the message must be sent 
to the same object that handled the mouse down. This method stores the 
event in the global gLastMouseUp. 

Key methods 

procedure DoKeyEvent (macEvent: EventRecord); 
void DoKeyEvent (EventRecord *macEvent); 

The user pressed or released a key. If the user holds down the Command 
key and presses a key at the same time, this method uses the Toolbox rou¬ 
tine MenuKey to find the menu equivalent. If there is a menu equivalent, 
this method sends a DoCommand message to the gopher. If there is no menu 
equivalent, this method sends a DoKeyDown message to the gopher. For 
other key events, this method send a DoKeyDown, DoKeyUp, or 
DoAutoKey messages to the gopher. 

Disk methods 

procedure DoDiskEvent (macEvent: EventRecord); 
void DoDiskEvent (EventRecord *macEvent); 

This method calls the Toolbox routine DIBadMount to mount a disk. This is 
the only event that the switchboard handles directly. 
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DoUpdate 


DoActivate 


DoDeactivate 


DoSuspend 


DoResume 


DoOtherEvent 


Doldle 


--- ♦ 

Window event methods 

procedure DoUpdate (macEvent: EventRecord); 
void DoUpdate (EventRecord *macEvent); 

This method sends an Update message to the window specified in the 
event record. 

procedure DoActivate (macEvent: EventRecord); 
void DoActivate (EventRecord *macEvent); 

This method sends an Activate message to the window specified in the 
event record. 

procedure DoDeactivate (macEvent: EventRecord); 
void DoDeactivate (EventRecord *macEvent); 

This method sends an Deact ivate message to the window specified in the 
event record. 

Suspend/Resume methods 

procedure DoSuspend (macEvent: EventRecord); 
void DoSuspend (EventRecord *macEvent); 

The application is about to be switched to the background under MultiFind- 
er. This method sends a Suspend message to your application. 

procedure DoResume (macEvent: EventRecord); 
void DoResume (EventRecord *macEvent); 

The application is about to be switched to the foreground under MultiFinder. 
This method sends a Resume message to your application. 

Event processing methods 

procedure DoOtherEvent (macEvent: EventRecord); 
void DoOtherEvent (EventRecord *macEvent); 

If your application handles applEvt, app2Evt, or app3Evt events, over¬ 
ride this method. 

procedure Doldle (macEvent: EventRecord); 
void Doldle (EventRecord *macEvent); 

This method is invoked during null events. This method sends an Idle 
message to your application. The application uses its Idle message to per¬ 
form periodic tasks. 
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D oH I g h Level Event 


DoAppleEvent 


AppleEventldle 


ProcessEvent 


procedure DoHighLevelEvent (macEvent: EventRecord); 
void DoHighLevelEvent (const EventRecord* macEvent); 
Handle a high level event. This method assumes all high level events are Ap- 
pleEvents. If you use a high level event that isn’t an AppleEvent, you must 
override this method. Your method should call inherited 
DoHighLevelEvent to handle AppleEvents. 

function DoAppleEvent (macEvent, theReply: AppleEvent; 
refCon: longint): OSErr; 

OSErr DoAppleEvent (AppleEvent *macEvent, 

AppleEvent *theReply, long refCon); 

Respond to an AppleEvent. This method packages the AppleEvent and the 
default reply into a CAppleEvent object and sends it to the gopher. If an ex¬ 
ception occurs, this method returns the error causing the exception. The ex¬ 
ception does not propagate beyond this method. 

This method calls sends the application a PackageAppleEvent message 
to package the event and its default reply into a CAppleEvent object. If you 
subclass CAppleEvent, override this method. 

function AppleEventldle (macEvent: EventRecord; 
var sleepTime: longint; mouseRgn: RgnHandle): 
Boolean; 

Boolean AppleEventldle (EventRecord *macEvent, 
long *sleepTime, RgnHandle *mouseRgn); 

The switchboard’s default AppleEvent idle procedure sends the switchboard 
this message. The Toolbox functions AEInteractWithUser and AESend 
use the idle procedure to respond to an event while waiting for the user to 
respond to an AppleEvent. The possible events are null, update, OS, or acti¬ 
vate events. 

To use a different idle procedure, set the idleProc instance variable in the 
CAppleEvent object, described on page 131. 

This method returns TRUE if the user aborted by pressing Command-. (Com¬ 
mand-Period), and FALSE if the user wants to continue waiting. 

procedure ProcessEvent; 
void ProcessEvent (void); 

This method is the heart of your application’s event loop. This method gets 
an event and sends a message to the switchboard to handle it. Before pro¬ 
cessing the event, ProcessEvent sends a DispatchCursor message to 
the application to adjust the cursor. 
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GetAnEvent 


DispatchEvent 
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function GetAnEvent (macEvent: EventRecord): Boolean; 
Boolean GetAnEvent (EventRecord *macEvent); 

Get the next event in the event queue. This method calls one of the Toolbox 
routines Get Next Event or WaitNextEvent to get an event and returns 
the result. If you need to do something to an event before the switchboard 
handles it, override this method. Your method should call inherited 
GetAnEvent and then do what you want with the event. 

procedure DispatchEvent (macEvent: EventRecord); 
void DispatchEvent (EventRecord *macEvent) 

This method is the main event dispatcher. Depending on the event, it sends 
an appropriate message back to itself to handle the event. 
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63 


Introduction 

CTask is an abstract class for implementing undoable actions. 

Heritage 

Superclass CObject 

Subclasses CMouseTask 

CTextEditTask 

CTextStyleTask 

Using CTask 

A task is an abstract class for implementing undoable actions. If you want 
your application to be able to undo an action, you need to define a task sub¬ 
class for each action. 

You can use a task two ways. You can perform your action, create a task ob¬ 
ject, store enough information in it for its Undo method to undo the action, 
and send it in a Notify message to your supervisor (usually the document). 

The second way is similar to the first, but you also implement a D o method 
that performs the action. So you create a task, send it a Do message to per¬ 
form the action, and then send it in a Notify message to your supervisor. 
Your Do method stores enough information in the task’s instance variables 
to undo the action. 

When you notify a document that you’ve performed a task, it stores the task 
in the instance variable lastTask. When you choose Undo from the Edit 
menu, the document’s DoCommand method sends an Undo message to that 
task. 

Every task subclass has a string in the S TR# 130 resource used f or the 
wording of the Undo/Redo command. Tasks have an instance variable that 
is the index of its string in the STR# resource. The document’s 
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UpdateUndo method takes care of the wording of the Undo/Redo com¬ 
mand. 

Here’s an example. Suppose you’ve defined a subclass of CTask to change 
the font in an edit text pane. Before passing the command on to the edit 
pane’s DoCommand method, you create a task and store the current font in 
an instance variable. After you pass the font command to the edit text pane, 
you send the task in a Notify message to the document. 

Your Undo method would simply send the font change command to the 
document. Since the command goes through the regular command chain, 
your DoCommand method would create a task to let you undo what you 
were undoing. 

Variables 

Variable Type 

namelndex integer 

undone Boolean 

Methods 

Initialization methods 
ITask procedure ITask (aNamelndex: integer); 

void ITask (short aNamelndex); 

Initialize a task object. ANamelndex is the index of the task’s Undo string in 
the STR# 130 resource. Your subclass’s initialization method should call 
this method in addition to any other initialization it does. If your task sub¬ 
class allocates memory, you’ll also need to implement a Free method to re¬ 
lease that memory. 

Accessing methods 

GetNamelndex function GetNamelndex: integer; 

short GetNamelndex (void); 

Get the task’s index. This method is used by the document’s UpdateUndo 
method. 

Islindone function IsUndone: Boolean; 

Boolean IsUndone (void); 

Return whether this task is undone. 


Description 

Index of the Undo/Redo 

string in the STR# 130 

resource. 

Is this task undone? 
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Class resources 


DoTask/Do 


Undo 


Redo 
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Action methods 

procedure DoTask; 
void Do (void); 

Perform a task. The default method does nothing. If you want to use a task 
to implement an action which is not necessarily undoable, your subclass 
should override this method. The Undo/Redo mechanism doesn’t send 
DoTask messages. 

procedure Undo; 
void Undo (void); 

Undo a task. The default method toggles the value of undone. Your sub¬ 
class must store enough information to be able to undo an action. This is the 
method where you implement the undo. 

procedure Redo; 
void Redo (void); 

Redo a task that was undone. The default method sends the task an Undo 
message. This method assumes that a redo is the same as undoing the undo. 
If your application implements Redo differently, you’ll need to override this 
method. 

Class resources 

Resource 

STR# 130 


Description 

List of strings for the wording of the 
Undo/Redo command. For instance, if 
you’re implementing a “move” action, 
your string would be “Move”. Each task 
contains the index of its string in this re¬ 
source. 
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64 


ITearChore 


Perform 


Introduction 

CTearChore is a chore the notifies a tear-off menut that it has been torn off. 

Heritage 

Superclass CChore 

Subclasses None 

Using CTearChore 

CTearChore is used in CTearOffMenu’s TornOf f method to let a menu that 
it has been torn off from the menu bar. TornOf f creates a tear chore and as¬ 
signs it as an urgent chore to the application. Your application should not 
have to use CTearChore directly, but you may find it useful as an example 
chore. 

Variables 

Variable Type Description 

itsTearOf fMenu CTearOf fMenu The tear-off menu that has 

been torn off. 


Methods 

procedure ITearChore (aTearOffMenu: CTearOffMenu); 
void ITearChore (CTearOffMenu *aTearOffMenu); 

Create a tear chore. ATearOf fMenu is stored in aTearOf fMenu. 
CTearOffMenu’s TornOf f method creates a tear chore and assigns it as an 
urgent chore. 

procedure Perform (var maxSleep: longint); 
void Perform (long *maxSleep); 

Sends a MoveToCorner method to itsTearOf fMenu. This method does 
not change maxSleep. 
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65 


Introduction 

CTearOffMenu is an abstract class that implements a Macintosh tear-off 
menu. 

Heritage 

Superclass CDirector 

Subclasses None 

Using CTearOffMenu 

CTearOffMenu is a director that holds the pane of a menu that has been torn 
off from the menu bar. To use a CTearOffMenu, you need to create a sub¬ 
class and override the initialization method so it creates a pane. Then create 
an MDEF class (CSelectorMDEF or another descendant of CPaneMDEF) and 
pass both the pane and the CTearOffMenu subclass to the initialization 
method. 

The window that CTearOffMenu uses to display the tear-off menu is a float¬ 
ing window. 

The Art Class example provided with the THINK Class Library uses two sub¬ 
class of CTearOffMenu for the tool palette and the pattern palette. 
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Variables 

Variable 

Type 

Description 

itsPane 

CPane 

The pane being displayed 

corner 

Point 

in the menu 

Top left of torn-off win¬ 

margins 

Rect 

dow. 

Space between window 

Methods 


bounds and the pane in 
the window 


ITearOffMenu procedure ITearOffMenu (aSupervisor: CApplication; 

WINDid: Integer); 

void ITearOffMenu (CApplication *aSupervisor, 
short WINDid); 

Create a director for a tear-off menu. A tear-off menu’s supervisor must be 
the application. WINDid is resource ID of the window that the tear-off menu 
appears in. Tear-off menus should use the Windoid WDEF. The source for 
this WDEF as well as the WDEF resource itself is in the FW/Tearof f s folder. 

ITearOffMenu sets itsPane to NIL, so your subclass needs to create a 
pane and set itsPane to it. This should be the same pane that you pass to the 
CPaneMDEF’s initialization method. 

procedure Suspend; 
void Suspend(void); 

Hides the tear-off menu when the application is suspended. 

procedure Resume; 
void Resume(void); 

Shows the tear-off menu when the application is reactivated.. 

procedure CloseWind(theWindow: CWindow); 
void CloseWind(CWindow *theWindow); 

Close the tear-off menu. To close the tear-off menu, this method moves its 
window off the screen. 


Suspend 


Resume 


CloseWind 
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TornOff 


MoveToCorner 


CetMacWindow 


SetMargins 


GetMargins 
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procedure TornOff(aCorner: Point); 
void TornOff(Point aCorner); 

The menu has been torn off to the point aCorner. This method creates a 
tear chore (see CTearChore on page 415) that moves the window to the ap¬ 
propriate location. 

procedure MoveToCorner; 
void MoveToCorner(void); 

Move the window to the corner stored by the TornOff method. 

function GetMacWindow(void): WindowPtr; 

WindowPtr GetMacWindow(void); 

Return the window record for the tear-off menu window. 

procedure SetMargins(aMargins: Rect); 
void SetMargins(Rect *aMargins); 

Set the margin between the window outline and the pane in the window. 
The margin is not a rectangle but the amount by which the pane’s frame 
should be enlarged to create the gray outline of the tear-off menu. 

procedure GetMargins(var theMargins: Rect); 
void GetMargins(Rect *theMargins); 

Return the margins in theMargins. 
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66 


Introduction 

CTextEditTask provides undo support for typing and editing in CAbstract- 
Text subclasses. 

Heritage 

Superclass CTask 

Subclasses None 

Using CTextEditTask 

CTextEdtTask implements undo for typing and the Cut, Copy, Paste, and 
Clear commands in CAbstractText subclasses. A text pane automatically cre¬ 
ates an instance of this class when you type, press Backspace or Forward 
Delete, or choose an editing command. 

You may need to create a subclass of CTextEditTask if you create your own 
subclass of CAbstractText, especially if your subclass allows text to have 
multiple styles or if it doesn’t store its text in a single contiguous block of 
memory. For example, a CStyleText text pane uses a task of type CSTyleTE- 
EditTask that can deal with the style scrap format. 
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Variables 

These are internal instance variables which only subclasses of CTextEditTask 
should use. In THINK C, they are protected. 


Variable 

Type 

Description 

itsTextPane 

CAbstractText 

Text pane that this 

editCmd 

longint 

task acts on. 
Command being 

inserted 

tTextRange 

performed, 
cmdNull if typing 
Info about the insert¬ 

deleted 

tTextRange 

ed text. 

Info about the delet¬ 

originalScrap 

Handle 

ed text 

Contents of text 

stillTyping 

Boolean 

scrap, before this 
task. 

TRUE if user is typ¬ 

doText 

Boolean 

ing. 

TRUE if this task 

doClip 

Boolean 

changes the text in 
the text pane 

TRUE if this task 

typingEvent 

EventRecord 

changes the clip¬ 
board. 

Event record for last 

Methods 

Creation and destruction methods 

keystroke. 


ITextEditTask procedure ITextEditTask (aTextPane: CAbstractText; 

anEditCmd: longint; firstTasklndex: integer); 

void ITextEditTask (CAbstractText *aTextPane, 
long anEditCmd, short firstTasklndex); 

Initialize this text edit task. AnEditCmd is the command that this task is re¬ 
sponding to, like cmdCut, cmdCopy, cmdPaste, or cmdClear. If the task 
is responding to typing, anEditCmd is cmdNull. ATextPane is the text 
pane for this task. FirstTasklndex is the index of the first text edit Undo 
string in STR# 130. The text edit Undo strings are typically “Typing,” 
“Cut,” “Copy,” “Paste,” and “Clear.” This method finds the index into STR# 
130 for anEditCmd, sets doClip to TRUE if this command will change 
the contents of the clipboard, or cmdCut, sets doText to TRUE if this corn- 
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Free/Dispose 


CanStlllType 


DoTask/Do 


DoTyping 


Undo 


Redo 
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mand adds or deletes text to the text pane, and saves the currently selected 
range. 

procedure Free; 
void Dispose (void); 

Dispose of the memory for this object. 

Accessing method 

function CanStillType: Boolean; 

Boolean CanStillType (void); 

Returns TRUE if the user’s typing doesn’t start a new task. The user can type 
if the user hasn’t tried to undo this task and stillTyping is TRUE. 

Action methods 

procedure Do; 
void Do (void); 

Perform an Edit menu command by sending the text pane a 
Perf ormEditCommand message. This method then stores the resulting se¬ 
lection 

procedure DoTyping (theChar: char; keyCode: integer; 
macEvent: EventRecord); 

void DoTyping (char theChar, short keyCode, 

EventRecord *macEvent); 

Type a character. Depending on the character, this methods calls 
DoBackspace, DoFwdDelete or DoNormalChar. This method is called 
only when performing a command, not when undoing one. 

procedure Undo; 
void Undo (void); 

Undo this task. This method saves the text the user inserted, removes the in¬ 
serted text, and restores the text the user deleted. If you chose Cut or Copy, 
it also restores the old clipboard. 

procedure Redo; 
void Redo (void); 

Redo this task, after it’s been undone. This removes the text the user deleted 
and restores the text the user inserted. If you chose Copy or Cut, it restores 
the new clipboard. 
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CancelTyping 


SelectionChanged 


DoNormalChar 


DoBackspace 


DoFwdDelete 


SaveRange 


DeleteRange 


procedure CancelTyping; 
void CancelTyping (void); 

Stop accumulating characters that the user types. This method is called if this 
task was created to handle typing and you have just stopped to move the 
cursor or select Undo. After this method is called, you can undo the typing 
until you start editing again or initiate another task. 

procedure SelectionChanged; 
void SelectionChanged (void); 

The selection has changed. This method sends a CancelTyping message. 

Internal methods 

procedure DoNormalChar (theChar: char); 
void DoNormalChar (char theChar); 

Handle a key that is not a Backspace or Forward Delete key, usually a cursor 
key or a character key. This method sends its text pane a TypeChar mes¬ 
sage. 

procedure DoBackspace; 
void DoBackspace (void); 

Handle the Backspace key. If you’re performing this task, this method saves 
the character you’re deleting. 

procedure DoFwdDelete; 
void DoFwdDelete (void); 

Handle the Forward Delete key. If you’re performing this task, this method 
saves the character you’re deleting. 

procedure SaveRange (whichRange: tRangeSelector); 
void SaveRange (tRangeSelector whichRange); 

If whichRange is kDeletedText, save the text the user is about to delete. 
If whichRange is klnsertedText, save the text the user just inserted. 

procedure DeleteRange (whichRange: tRangeSelector); 
void DeleteRange (tRangeSelector whichRange); 

If whichRange is kDeletedText, delete the text the user deleted. If 
whichRange is klnsertedText, delete the text the user inserted. 
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RestoreRange 


StoreToClip 


procedure RestoreRange (whichRange: tRangeSelector; 
killData: Boolean); 

void RestoreRange (tRangeSelector whichRange, 

Boolean killData); 

If whichRange is kDeletedText, restore the text the user deleted If 
whichRange is klnsertedText, restore the text the user inserted. If 
killData is TRUE, this method disposes of this object’s copy of the re¬ 
stored text. 

procedure StoreToClip (whichClip: tClipSelector); 
void StoreToClip (tClipSelector whichClip); 

If whichClip is kOldClip, store the original scrap text. If whichClip is 
kNewClip, store the deleted text to the clipboard. 
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Introduction 

CTextStyleTask provides undo support for style commands in CAbstractText 
subclasses. 

Heritage 

Superclass CTask 

Subclasses CStyleTEStyleTask 

Using CTextStyleTask 

CTextStyleTask provides undo support for font, size, style, alignment, and 
spacing commands in CAbstractText subclasses. A text pane automatically 
creates an instance of this class when you choose a style command. 

You may need to create a subclass of CTextStyleTask if you create your own 
subclass of CAbstractText, especially if your subclass allows text to have 
multiple styles or if it doesn’t store its text in a single contiguous block of 
memory. For example, a CStyleText text pane uses a task of type CStyleTES¬ 
tyleTask that can deal with the style scrap format. 
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ITextEditTask 


DoTask/Do 


Undo 


Variables 

These are internal instance variables which only subclasses of CTextStyle¬ 
Task should use. In THINK C, they are protected. 


Variable 

itsTextPane 

oldStyle 

oldLAlignCmd 

oldSpacingCmd 

styleCmd 

styleAttribute 


Type 

CAbstractText 

TextStyle 

longint 

longint 

longint 

integer 


Description 

Text pane that this 
task acts on. 

Style before this task. 
Alignment before 
this task. 

Spacing before this 
task. 

Command this task 
performs. 

Style attributes af¬ 
fected by this task. 


Methods 

Construction method 

procedure ITextStyleTask (aTextPane: CAbstractText; 
aStyleCmd: longint; tasklndex: integer); 

void ITextStyleTask (CAbstractText *aTextPane, 
long aStyleCmd, short tasklndex); 

Initialize this text style task. AStyleCmd is the command that this task is re¬ 
sponding to. ATextPane is the text pane for this task. Tasklndex is the 
index of this command’s Undo string in STR# 130. 


Action methods 

procedure DoTask; 
void Do (void); 

Save the original formatting, then performs the user’s formatting command. 


procedure Undo; 
void Undo (void); 

Save the current formatting and restore the previously saved formatting. This 
method handles both Undo and Redo. 
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SaveStyle 


RestoreStyle 


-- 4 

Internal methods 

procedure SaveStyle; 
void SaveStyle (void); 

Save the style of the text. Depending on the text pane, this method saves ei¬ 
ther the style for the whole text pane (like CEditText) or the style for the cur¬ 
rent selection (like CStyleText). 

procedure RestoreStyle; 
void RestoreStyle (void); 

Restores the previously saved formatting. 
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Introduction 

CTextEnvirons maintains a Quickdraw text drawing environment for any 
pane. 

Heritage 

Superclass CEnvironment 

Subclasses None 

Using CTextEnvirons 

Every pane has an itsEnvironment instance variable. If this variable 
points to a descendant of CEnvironment, the Prepare method sends it a 
Restore message to set up the drawing environment for the pane. 

You can use CTextEnvirons to make sure that a pane’s text drawing charac¬ 
teristics are set up correctly. CTextEnvirons maintains the font, the size of the 
font, the font style, and the drawing transfer mode. 

Suppose you have a pane that lets the user set the font and size of a text dis¬ 
play. When you create your pane, you read the settings into a 
Text Inf oRec, create a CTextEnvirons object, then set the 
itsEnvironment instance variable to point to it. Whenever the pane 
needs to be drawn, the Prepare method sends it a Restore message so 
the drawing mode is set up correcdy. 
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Here’s how you might set up a CTextEnvirons object for a pane in Pascal: 

procedure CSomeDisplayPane.ISomeDisplayPane ( 
anEnclosure: CView; 
aSupervisor: CBureaucrat); 

var 

aTextlnfo: TextlnfoRec; 

begin 

aTextlnfo.fontNumber := ReadStoredFont; 
aTextlnfo.theSize := ReadStoredSize; 
aTextlnfo.theStyle := []; 
aTextlnfo.theMode := srcCopy; 
new(CTextEnvirons(itsEnvironment)); 
CTextEnvirons(itsEnvironment).SetTextlnfo 

(aTextlnfo); 


end; 

Here’s how you might do the same thing in C: 

void CSomeDisplayPane :: ISomeDisplayPane ( 

CView *anEnclosure, 

CBureaucrat *aSupervisor) 

{ 

TextInfoRec aTextlnfo; 

aTextlnfo.fontNumber = ReadStoredFont(); 
aTextlnfo.theSize = ReadStoredSize (); 
aTextlnfo.theStyle = 0; 
aTextlnfo.theMode = srcCopy; 
itsEnvironment = new CTextEnvirons; 
((CTextEnvirons *) itsEnvironment)-> 

SetTextlnfo(SaTextlnfo); 

} 

Variables 

Variable Type 

textlnfo TextlnfoRec 

The TextlnfoRec looks like this: 

Field Type 

fontNumber Integer 

theSize Integer 

theStyle Style 

theMode Integer 


Description 

Text characteristics 


Description 

The number of the font 
Size of the font 
Style of the font (in THINK 
C, this type is short) 
Text transfer mode 
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ITextEnvirons 


Restore 


SetTextlnfo 


GetTextlnfo 
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Methods 

procedure ITextEnvirons; 
void ITextEnvirons (void); 

Initialize every field of the text Info record to zero. These settings corre¬ 
spond to the default system font, the default system size, plain style, and the 
scrCopy transfer mode. 

procedure Restore; 
void Restore (void); 

Sets the Quickdraw text drawing characteristics to the values previously 
stored with SetTextlnfo. This method uses the standard QuickDraw text 
setting routines: TextFont, Text Size, TextFace, and TextMode. This 
method also calls the Toolbox routine PenNormal. 


procedure SetTextlnfo (aTextlnfo: TextlnfoRec); 
void SetTextlnfo (TextlnfoRec *aTextInfo); 

Sets the text drawing characteristics to the values in aTextlnfo. The next 
time the pane is redrawn, the QuickDraw text drawing characteristics will be 
set to the values supplied. 

procedure GetTextlnfo (var aTextlnfo: TextlnfoRec); 
void GetTextlnfo (TextlnfoRec *aTextInfo);; 

Get the current text drawing characteristics from the object. 
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Introduction 

CView is an abstract class for implementing objects that have a visual repre¬ 
sentation. Every object in the visual hierarchy is a descendant of this class. 

Heritage 

Superclass CBureaucrat 

Subclasses CDesktop 

CPane 
C Window 

Using CView 

CView is an abstract class for implementing objects with a visual representa¬ 
tion. In other words, anything you can see on the screen is a descendant of 
CView. Views respond to visual commands involving the mouse. And be¬ 
cause CView is a descendant of CBureaucrat, a view can be one of the links 
in the chain of command. 

The standard classes define three subclasses of CView. These are the desk¬ 
top, windows, and panes. Most of the time, you’ll be dealing with panes. As 
you work with panes and descendants of CPane, keep in mind that all meth¬ 
ods that apply to views apply to them as well. 

Views and the visual hierarchy 

All views have an enclosure that specifies its place in the visual hierarchy. 
Each view can enclose several subviews. The top of the visual hierarchy, the 
desktop, is the only view that does not have an enclosure. The desktop en¬ 
closes all the windows in your application. Each window encloses one or 
mores panes. Panes can enclose other panes. 

The desktop handles some visual commands, like mouse clicks, and sends 
them on to the appropriate window. The switchboard sends window related 
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messages, like updates and activates, directly to a window which sends it to 
its subviews. 

By default, a view does not process mouse clicks. If a view can respond to 
mouse clicks, you need to call SetWantsClicks (TRUE) when you create 
it to let DispatchClick and Ad justCursor know that they should look 
for clicks in mouse movement in that view. 

Views and the chain of command 

Each view has a supervisor which is the view’s boss in the chain of com¬ 
mand. The desktop’s supervisor is always the application. A window’s su¬ 
pervisor is always its director or document. A pane’s supervisor is usually its 
director or document. 

The desktop and windows are almost never the first in the chain of com¬ 
mand. In other words, they’re almost never the gopher. Panes, on the other 
hand, are frequently made the gopher. For instance, you need to make an 
edit pane the gopher so it can respond to typing and menu commands. 

If a view can be a gopher, you need to call SetCanBeGopher (TRUE) so 
DispatchClick can make the view the gopher and let the previous go¬ 
pher know that it’s not the gopher anymore. Although you can force a view 
to be the gopher by setting the gGopher instance variable, you should rely 
on the gopher-setting mechanism of BecomeGopher. 

Using Balloon Help with views 

Any view can have a help balloon associated with it. The THINK Class Li¬ 
brary uses 'hrct' resources to specify help balloons. The Macintosh Help 
Manager, described in Inside Macintosh VI, uses a combination of ' hwin' 
and ' hrct' resources to display help balloons for stationary windows. The 
THINK Class Library uses only 'hrct* resource. They should not be associ¬ 
ated with ' hwin 1 resources. 

Each window holds a resource ID to an 1 hrct' resource for help associat¬ 
ed with that window. If the window doesn’t provide a resource ID for the 
' hrct' resource, it uses the default ' hrct' resource whose ID is 
kDef aultHelpResID (128). 

If you want to provide help for a pane, set the helpRes Index instance 
variable, which it inherits from CView, as an index into the ' hrct 1 re¬ 
source. Otherwise, just set helpRes Index to 0. 

The DispatchCursor method uses GetBalloonlnf o and ShowHelp- 
Balloon to look for the help resource and to display them. 
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Variables 



Variable 

Type 

Description 

macPort 

GrafPtr 

Mac drawing port for the 
view 

itsEnclosure 

CView 

View which totally enclos¬ 
es this one 

itsSubviews 

CList 

Views contained within 
this view 

visible 

Boolean 

Is the view visible? 

active 

Boolean 

Is the view active? 

wantsClicks 

Boolean 

Does the view handle 
mouse clicks? 

canBeGopher 

Boolean 

Can this view be the go¬ 
pher? 

ID 

longint 

The identifier for this view. 

usingLongCoord Boolean 

TRUE if using 32-bit coor¬ 
dinates 

helpResIndex 

integer 

Index into 1 hrct 1 re¬ 
source for balloon help 


IView 


The following three variables are class variables. In Pascal these are global 
variables. CView uses these class variables for tracking help balloons and for 
optimizing calls to Prepare. In general, you won’t need to use them. 


Variable Type 

cCurrHelpView CView 

cLastHelpView CView 
cPreparedView CView 


Description 

Used in DispatchCur- 
sor to determine wheth¬ 
er a help balloon was 
displayed 

The view that is showing a 
help balloon 
Currently prepared view 


Methods 

Construction and destruction methods 

procedure IView (anEnclosure: CView; 
aSupervisor: CBureaucrat); 

void IView (CView *anEnclosure, 

CBureaucrat *aSupervisor); 

Initialize a view. Views start out with no port, no subviews, invisible, and in¬ 
active. By default, views don’t want clicks. AnEnclosure is the view that 
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IViewRes 


IViewTemp 


Free/Dispose 


IsVisible 


IsActive 


ReallyVisible 


completely encloses this view. ASupervisor is the bureaucrat that gets com¬ 
mand messages for the commands this view can’t handle. 

procedure IViewRes (rType: ResType; resID: integer; 
anEnclosure: CView; aSupervisor: CBureaucrat); 

void IViewRes (ResType rType, short resID, 

CView *anEnclosure, CBureaucrat *aSupervisor); 

Initialize a view from a resource template. Each subclass of CView overrides 
this method to use its own resource template. RType is the resource type for 
the CView subclass you want to initialize. Res ID is the resource ID of the re¬ 
source. AnEnclosure is the view that completely encloses this view. 
ASupervisor is the bureaucrat that gets command messages when the 
view can’t handle them. 

To initialize a view from a resource file, use a * View' resource. 

procedure IViewTemp (anEnclosure: CView; 

aSupervisor: CBureaucrat; viewData: Ptr); 

void IViewTemp (CView *anEnclosure, 

CBureaucrat *aSupervisor, Ptr viewData); 

The IViewRes method sends an IViewTemp message to initialize a view 
from a resource template. All subclasses of CView override this method so 
they can be initialized from resource templates. 

procedure Free; 
void Dispose (void); 

Dispose of a view. Disposes of all subviews 

Accessing methods 

function IsVisible: Boolean; 

Boolean IsVisible (void); 

Return TRUE if the view is visible. 

function IsActive: Boolean; 

Boolean IsActive (void); 

Return TRUE if the view is active. 

function ReallyVisible: Boolean; 

Boolean ReallyVisible (void); 

Return TRUE if the view is visible and if its enclosure is ReallyVisible. 
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GetMacPort 


GetOrlgln 


GetFrame 


Getlnterior 


GetAperture 


Contains 


SetWantsClicks 


GetWantsClicks 


- —- ♦ 

function GetMacPort: GrafPtr; 

GrafPtr GetMacPort (void); 

Get the Graf Port associated with this view. 

procedure GetOrigin (var theHOrigin, 
theVOrigin: longint); 

void GetOrigin (long *theHOrigin, long *theVOrigin); 
Get the origin of the view (the top left corner). The default method returns 
( 0 , 0 ). 

procedure GetFrame (var theFrame: LongRect); 
void GetFrame (LongRect *theFrame); 

Get the frame of the view. The default method does nothing. View subclass¬ 
es (like Pane) must override this message. 

procedure Getlnterior (var thelnterior: LongRect); 
void Getlnterior (LongRect *theInterior); 

Get the interior of the view. The default method returns what GetFrame re¬ 
turns. If the interior of a particular subclass is not the same as the frame, the 
class must override this method. 

procedure GetAperture (var theAperture: LongRect); 
void GetAperture (LongRect *theAperture); 

Get the aperture of the view. (The aperture is the visible portion of a view.) 
The default method does nothing. Subclasses must override this method. 

function Contains (thePoint: Point): Boolean; 

Boolean Contains (Point thePoint); 

Return TRUE if the view contains thePoint. The default method always re¬ 
turns FALSE. 

procedure SetWantsClicks (aWantsClicks: Boolean); 
void SetWantsClicks (Boolean aWantsClicks); 

If aWantsClicks is true, the view will report clicks in itself. By default, 
views don’t want clicks. 

function GetWantsClicks: Boolean; 

Boolean GetWantsClicks (void); 

Returns TRUE if this view wants to receive clicks 
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SetCanBeCopher 

CanBeCopher 

SetID 


CetID 

UseLongCoordinates 


Show 

Hide 

Activate 


procedure SetCanBeGopher (fCanBeGopher: Boolean); 
void SetCanBeGopher (Boolean fCanBeGopher) 

If fCanBeGopher is TRUE, this view can become the gopher. By default, a 
view can’t become the gopher. 

function CanBeGopher: Boolean; 

Boolean CanBeGopher (void) 

Returns TRUE if this view can become the gopher. 

procedure SetID (anldentifier: longint); 
void SetID (long anldentifier) 

Sets this view’s ID to be anldentif ier. By default, the ID is 0 (zero). It is 
up to you to provide IDs and to guarantee that they’re unique. View IDs give 
you a way to identify particular views within the view hierarchy. You can 
use Macintosh style identifiers like ’MyVu* or plain numeric constants. 

function GetID: long; 
long GetID (void) 

Returns the ID for this view. 

procedure UseLongCoordinates (fusing: Boolean); 
void UseLongCoordinates (Boolean fusing) ; 

Specify whether the view should use 32-bit coordinates Gong coordinates) 
or 16-bit QuickDraw coordinates. If fusing is TRUE, the view is using 32- 
bit coordinates. 

Appearance methods 

procedure Show; 
void Show (void); 

Make a view visible. 

procedure Hide; 
void Hide (void); 

Hide a view. If the view is the gopher, make its supervisor the gopher. 

procedure Activate; 
void Activate (void); 

Make a view active. Activate all the subviews as well. 
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Deactivate 


DispatchClick 


DoCIIck 


These conversion routines 
are described on page 333 


HitSamePart 


DoMouseUp 


♦ 


procedure Deactivate; 
void Deactivate (void); 

Make a view inactive. Deactivate all the subviews as well. If the view is the 
gopher, make its supervisor the gopher. 

Mouse methods 

procedure DispatchClick (var macEvent: EventRecord); 
void DispatchClick (EventRecord *macEvent); 

Find out which subview got the click and send it a DispatchClick mes¬ 
sage. If there are no subviews, the click is for this view. If the view can be 
the gopher, DispatchClick calls BecomeGopher (TRUE) to make the 
view the gopher. Then DispatchClick sets calls Prepare to set up the 
drawing environment. Finally, DispatchClick sends aDoClick mes¬ 
sage to the view to handle the click. Ordinarily, you should not need to 
override this method. 

procedure DoClick (hitPt: Point; 

modifierKeys: integer; when: longint); 

void DoClick (Point hitPt, short modifierKeys, 
long when); 

The mouse went down in this view. If the view is not using long coordi¬ 
nates, hitPt is in frame coordinates. If the view is using long coordinates, 
hitPt is given in QuickDraw coordinates. You can use CPane’s QDToF- 
rame, QDToFrameRto convert from long coordinates to frame coordinates, 
and FrameToQD and FrameToQDR to convert from long coordinates to 
QuickDraw coordinates. Subclasses must override this method. 

function HitSamePart (var pointA, pointB: Point) : 
Boolean; 

Boolean HitSamePart (Point pointA, Point pointB); 

Check whether two points hit the same part of the view. The default method 
always returns TRUE. Subclasses that override this method should decide 
what constitutes a part and how close is close. 

procedure DoMouseUp (macEvent: EventRecordPtr); 
void DoMouseUp (EventRecord *macEvent); 

The mouse went up in a view. Default method does nothing. 
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DispatchCursor 


Ad just Cursor 


Cursor methods 

procedure DispatchCursor (where: Point; 
mouseRgn: RgnHandle); 

void DispatchCursor (Point where, RgnHandle mouseRgn); 
Find which view the cursor is in. If the cursor is in this view, send it an 
Ad justCursor message. If the cursor is in a subview, send it a 
DispatchCursor message. DispatchCursor sends AdjustCursor 
and DispatchCursor messages only to views that want clicks. 

If the balloon help system is available, and the application has help resourc¬ 
es, and no other view has already displayed the help text, 
DispatchCursor display the help balloon associated with this view. 

Your application should not need to override this class. 

procedure AdjustCursor (where: Point; 
mouseRgn: RgnHandle); 

void AdjustCursor (Point where, RgnHandle mouseRgn); 

Adjust the cursor. A view gets an AdjustCursor message when the cursor 
moves into it and if the view wants clicks. The default method sets the cursor 
to an arrow. Your subclass should override this method to set the cursor to 
whatever is appropriate for the view. See the AdjustCursor method for 
CAbstractText for an example. 

If you use only one cursor within a view, you can ignore the two parameters 
to this method. If you want to use different cursor shapes within a pane, you 
need use these two parameters. 

It’s unlikely that you’ll want multiple cursors for a view that’s not a pane. 
The CPane class inherits this method. 

The where parameter tells you where the cursor is in window coordinates. 
You can use the WindToFrame pane method to convert it to frame coordi¬ 
nates. The mouseRgn parameter is the region in which the cursor shape 
stays the same. In other words, your pane will not get an AdjustCursor 
message again until the cursor leaves this region. The mouseRgn is speci¬ 
fied in global coordinates. 

Suppose you’re displaying a map of the United States in a pane, and you 
want the cursor to be a star when it’s over Texas. You use the where param¬ 
eter, converted from window coordinates to frame coordinates, to determine 
that you’re in Texas, and you change the cursor to a star. 
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Now, when you leave Texas, you want to set the cursor shape to something 
else. Since your pane gets Ad just Cursor messages only when the cursor 
leaves the mouseRgn, you have to change the mouseRgn. You create a re¬ 
gion with the shape of the state of Texas, convert this region to global coor¬ 
dinates, and make it the mouseRgn. 


Note ~ 

The mouse region should be the intersection of the original 
mouse region and the one you’re specifying. This way, you 
preserve any clipping boundaries that the original mouse 
region had accounted for. 


This is what the Ad justCursor method for this example might look like in 
Pascal: 

procedure MapPane.AdjustCursor (where: Point; 
mouseRgn: RgnHandle); 

var 

locWhere: Point; 

TexasRgn: RgnHandle; 

TexasRect: Rect; 
tempRect: Rect; 

begin 

TexasRgn := NewRgn; 
locWhere := where; 

WindToFrame(locWhere); 

{ If we're not in Texas, } 

{ use the default. } 

if (not PtlnTexas(locWhere)) then 
begin 

inherited AdjustCursor(where, mouseRgn); 
exit(AdjustCursor) ; 
end 

{ Set the star cursor. } 

SetCursor(star); 

{ Calculate the mouse region } 

{ in frame coords. } 

OpenRgn; 

DrawTexas; 

CloseRgn(TexasRgn); 
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{ Convert it to global coords. } 

TexasRect := TexasRgn AA .rgnBBox; 
tempRect := TexasRect; 

FrameToGlobalR(tempRect); 

OffsetRgn(TexasRgn, 

tempRect.left - TexasRect.left 
tempRect.top - TexasRect.top); 

{ Set the mouse region. } 

SectRgn(mouseRgn, TexasRgn, mouseRgn); 
end; 

And this is what the Ad just Cursor method might look like in C: 

void MapPane::AdjustCursor(Point where, 
RgnHandle mouseRgn); 

{ 

Point locWhere; 

RgnHandle TexaxRgn = NewRgn(); 

Rect TexasRect; 

Rect TempRect; 

locWhere = where; 

WindToFrame(&locWhere); 

/* If we're not in Texas, */ 

/* use the default. */ 

if ( IptlnTexas(locWhere)) { 

inherited::AdjustCursor(where, mouseRgn); 
return ; 

} 

/* Set the star cursor. */ 

SetCursor(star); 

/* Calculate the mouse region */ 

/* in frame coords. */ 

OpenRgn(); 

DrawTexas (); 

CloseRgn(TexasRgn); 

/* Convert it to global coords. */ 
TexasRect = (**TexasRgn).rgnBBox; 
tmpRect = TexasRect; 

FrameToGlobalR(StempRect); 

OffsetRgn(TexasRgn, 

tempRect.left - TexasRect.left, 
tempRect.top - TexasRect.top) 

/* Set the mouse region. */ 

SectRgn(mouseRgn, TexasRgn, mouseRgn); 

} 
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ShowHelpBalloon 


GetHelpResID 


AddSubview 
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procedure GetBalloonlnfo ( 

var helpData: HMMessageRecord; var tip: Point; 
var altertnateRect: Rect; var tipProc: Ptr; 
var variant: integer; var method: integer); 

void GetBalloonlnfo (HMMessageRecord *helpData, 

Point *tip, Rect *alternateRec, Ptr *tipProc, 
short *theProc, short *variant, short *method); 

Set up the parameters needed to show a help balloon. If heIpResIndex is 
greater than 0, use it as an index into the 1 hrct 1 resource associated with 
this view. If the view is a pane, the enclosing window holds the resource id 
of the ' hrct 1 resource, otherwise it uses 1 hrct 1 with the ID kDefault- 
HelpResID (128). 

This method calls the Help Manager’s HMGetlndHelpMsg routine to get 
the information from the ' hrct' resource. 

procedure ShowHelpBalloon (helpData: HMMessageRecord; 
tip: Point; altertnateRect: Rect; tipProc: Ptr; 
variant: integer; method: integer); 

void ShowHelpBalloon (HMMessageRecord *helpData, 

Point tip, Rect *altRec, Ptr tipProc, 
short theProc, short variant, short method); 

This method uses the data from GetBalloonlnfo and calls the Help Man¬ 
ager routine HMShowBalloon to display the help balloon. If there is an er¬ 
ror, this method calls Failure. HelpData comes from the 1 hrct' 
resource. Tip, as returned from GetBalloonlnfo is set to the center of 
the view, in global coordinates. AltRect is the aperture of the view. Tip¬ 
Proc is NIL. TheProc is 0, the standard definition function. Variant and 
method are both read from the 'hrct' resource. 

function GetHelpResID : integer; 
short GetHelpResID (void); 

Return the resource ID of the 1 hrct' resource that has the balloon help in¬ 
formation for this view. This method returns the ID of the TCL’s default 
' hrc' resource: kDef aultResID. 

Subview Management methods 

procedure AddSubview (theSubview: CView); 
void AddSubview (CView *theSubview); 

Add theSubview to the view’s itsSubviews list. You should not use or 
override this method. 
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RemoveSubview 

FindSubview 

FlndViewBylD 

MatchVlew 


SubpaneLocation 


procedure RemoveSubview (theSubview: CView); 
void RemoveSubview (CView *theSubview); 

Remove theSubview from the itsSubviews list. 

function FindSubview (hitPt: Point): CView; 

CView* FindSubview (Point hitPt); 

Find the subview that wants clicks and contains hitPt. HitPt is in win¬ 
dow coordinates. This method finds the topmost subview. You should not 
override this method. 

function FindViewBylD (anID: longint): CView; 

CView* FindViewBylD (long anID); 

Find the subview whose ID is anID. If more than one view has the same ID, 
this method Finds the topmost subview. 

function MatchView (function matchProc(aView: CView; 
matchData: Ptr): Boolean; 
matchData: Ptr): CView; 

CView* MatchView (MatchViewProc matchProc, 
void *matchData) 

Find the First subview that returns TRUE for matchProc. This method Finds 
the topmost subview. 

MatchProc is a pointer to function of the form: 

function matchProc (aView: CView; 
matchData: Ptr); 


or in C: 

Boolean matchProc (CView *aView, 
void *matchData); 

MatchData can be anything that your matchProc needs. For an example 
of MatchView, see the definition of FindViewBylD. 

procedure SubpaneLocation (hEncl, vEncl: longint; 
var hLocation, vLocation: longint); 

void SubpaneLocation (long hEncl, long vEncl, 
long *hLocation, long *vLocation); 

Return the position of a subview at hEncl, vEncl in hLocation and 
vLocation in window coordinates. 
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Prepare 


ForceNextPrepare 


FrameToGlobaIR 
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procedure Prepare; 
void Prepare (void); 

Prepare to draw or to do something after a click. The default method sets the 
class variable cPreparedView to this. The class variable 
cPreparedView points to the most recently prepared view. CPane uses 
cPreparedView to avoid redundant calls to Prepare. 

View classes must override this method. The overriden methods should set 
cPreparedView to this or call the inherited method. See the definition 
of Prepare in CPane for an example. 

procedure ForceNextPrepare; 
void ForceNextPrepare (void); 

Clear cPreparedView to disable the optimization on the next call to 
Prepare. If you change the port, the clipping region, or the origin of a 
view, you must call this method to disable the Prepare optimization. 

procedure FrameToGlobaIR (frameRect: LongRect; 
var globalRect: Rect); 

void FrameToGlobaIR (LongRect *frameRect, 

Rect *globalRect); 

Convert frameRect from frame coordinates to global coordinates and put 
the converted coordinates into globalRect. The default method does 
nothing. View subclasses must override thismethod. 

Class resources 

The IViewRes method lets you initialize any descendant of CView with a 
resource template. 


Resource 

Class 

Bord 

CBorder 

Pane 

CPane 

Pano 

CPanorama 

PctP 

CPicture 

ScPn 

CScollPane 

StTx 

CStaticText, CEditText 

View 

CView 


You can use ResEdit to create the resource templates for each class. 
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Note 

Your package includes a file called TCL TMPLs that con¬ 
tains a set of TMPL resources you can install into ResEdit. 
These TMPLs let you create and edit the resource above 
easily. See the instructions in “Installing the TMPL Resourc¬ 
es into ResEdit” in Chapter 2 to learn how to install these 
TMPLs into ResEdit. 
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Introduction 

CWindow implements a class necessary to manipulate a Macintosh window. 

Heritage 

Superclass CView 

Subclasses None 

Using CWindow 

Virtually every application you write on the Macintosh uses windows. The 
CWindow class implements methods to manipulate Macintosh windows. In 
the THINK Class Library, window objects are merely visual entities. They’re 
not designed to interact directly with the application. The class CDirector 
manages communication between a window and the application. The 
CDocument class, a subclass of CDirector, manages communication be¬ 
tween the application, a window, and a file. 

Objects of class CWindow usually belong to directors. Under normal circum¬ 
stances, you should not need to define a subclass of CWindow or to manip¬ 
ulate one directly. The only thing you really need to do to a window is 
create it and set its options. 

You can specify that a window be modal. If a modal window is the front- 
most window, CDesktop’s DispatchClick method will not let a click in 
another window deactivate the modal window, though mouse clicks in the 
menu bar are handled. Be sure that your program provides a way to close 
modal windows. 

The Macintosh windows associated with CWindow objects have a window 

kind of OBJ_WINDOW_KIND. If your application uses windows that are not 

associated with a CWindow object— from a utility library, for instance—you 
should override the CDesktop methods DispatchClick and 
DispatchCursor and the CSwitchboard methods DoUpdate, 
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DoActivate, and DoDeactivate to check the window kind of the Mac¬ 
intosh windows they deal with. 

Variables 

The enclosure for all windows must be gDesktop. 


Global variable 

Variable 

Type 

Description 

gDesktop 

CDesktop 

The global desktop which 
acts as the top of the visual 
hierarchy and the enclo¬ 
sure for all windows. 

Instance variables 

Variable 

Type 

Description 

procID 

integer 

Window definition ID 
used to create the win¬ 
dow. 

sizeRect 

Rect 

Minimum and maximum 
size of the window 

floating 

Boolean 

Is this a floating window? 

isColor 

Boolean 

Is this a color window? 

isModal 

Boolean 

Is it currently modal? 

actClick 

Boolean 

Process mouse click which 
activates window? 

location 

Point 

Current window location, 
used when “hiding” a win¬ 
dow while suspended 

helpResID 

integer 

Resource ID of 1 hrct 1 


help resource for panes in 
this window. 


Methods 

Construction and destruction methods 
IWindow procedure IWindow (WINDid: integer; 

aFloating: Boolean; anEnclosure: CDesktop; 
aSupervisor: CDirector); 

void IWindow (short WINDid, Boolean aFloating, 
CDesktop *anEnclosure, 

CDirector *aSupervisor); 

Initialize a window object from a WIND resource. If Color QuickDraw is 
available, this method creates a color window. 
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INewWindow 


Free/Dispose 


- --- * 

WINDid is the id of the WIND resource. If aFloat ing is true, the window is 
a floating window. In this case, anEnclosure must refer to a floating win¬ 
dow desktop. 

AnEnclosure is the view the window belongs to. A window’s enclosure 
should always be gDesktop. ASupervisor is the window’s supervisor. 
Usually a window’s supervisor is the director it belongs to. IWindow sends 
the window a MakeMacWindow message to actually allocate space in mem¬ 
ory for the window. 

By default, a window is not modal. To make a window modal, use the Set- 
Modal method onpage 453. 

By default, helpResID is set to kDef aultResID. HelpResIDis the re¬ 
source ID of the ' hrct' resource associated with this window. To change it 
use the SetHelpReslD method on page 454. For more information about 
using Balloon Help with panes, see “Using Balloon Help with views” on 
page 436. 

procedure INewWindow (bounds: Rect; 

fVisible: Boolean; aProcID: integer; 
fFloating: Boolean; Boolean fHasGoAway 
anEnclosure: CDesktop; aSupervisor: CDirector); 

void INewWindow (Rect *bounds. 

Boolean fVisible, short aProcID, 

Boolean fFloating, Boolean fHasGoAway, 

CDesktop *anEnclosure, 

CDirector ^aSupervisor); 

Initialize a window from the parameters in the argument list. If Color Quick¬ 
Draw is available, this method creates a color window. 

Bounds is a rectangle that describes the size and position of the window. 

AP roc ID is an integer that describes that type of the window. 

If fVisible is TRUE, the window is drawn immediately after it’s created. If 
fHasGoAway is TRUE, the window has a close box in. 

The other parameters are identical to I Window’s parameters above. 

procedure Free; 
void Dispose(void); 

Dispose of the window and all of its subpanes. This method also removes 
the window from the desktop. 
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MakeMacWindow 


MakeNewMacWindow 


Close 


GetFrame 


Getlnterior 


procedure MakeMacWindow (WINDid: integer); 
void MakeMacWindow (short WINDid); 

Create a Macintosh window from a WIND resource. This method lets the 
Window Manager allocate memory itself. If you want to create your win¬ 
dows differently, override this method. Bear in mind that floating windows 
should be in front (-1) and that non-floating windows should be behind. 

procedure MakeNewMacWindow (bounds: Rect; 
aProcID: integer; fHasGoAway: Boolean); 

void MakeNewMacWindow (Rect *bounds, short aProcID, 
Boolean fHasGoAway) 

Create a Macintosh window from the parameters in the argument list. 
Bounds is a rectangle that describes the size and position of the window. 
AProc ID is an integer that describes that type of the window. If 
FHasGoAway is TRUE, the window will have a close box in the left side of 
the title bar. 

This method lets the Window Manager allocate memory itself. If you want to 
create your own windows differently, override this method. For example, 
you might want to perform your own memory allocation or to create color 
windows. For compatibility with the Desktop class, the convention of put¬ 
ting floating windows in front and non-floating windows in back should be 
observed. Bear in mind that floating windows should be in front (-1) and 
that non-floating windows should be behind. 

procedure Close; 
void Close (void); 

Close a window. A window object gets this message as a result of a click in 
the close box. The default method sends the window’s supervisor (a direc¬ 
tor) a CloseWind message. 

Accessing methods 

procedure GetFrame (var theFrame: LongRect); 
void GetFrame(LongRect *theFrame); 

Get the frame of a window. The frame of the window includes the one pixel 
border around the window. The top, left of theFrame is always (-1,-1) 

procedure Getlnterior (var thelnterior: LongRect); 
void Getlnterior(LongRect *theInterior); 

Get the interior of a window. The interior of the window is the same as its 
portRect and does not include any of the border pixels. The top left of 
thelnterior is always (0, 0). 
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GetAperture 


IsFloating 


IsModal 


SetModal 


IsColor 


SetTItle 


GetTItle 


SetActClick 


WantsActClick 


- -- ♦ 

procedure GetAperture (var theAperture: LongRect); 
void GetAperture (LongRect *theAperture); 

Return the drawable area of the window. For windows, this is the entire win¬ 
dow. The top, left of theAperture is always (0,0). 

function IsFloating: Boolean; 

Boolean IsFloating (void); 

Return TRUE if this is a floating window. 

function IsModal: Boolean; 

Boolean IsModal (void); 

Return TRUE if this is a modal window. 

procedure SetModal (fModal: Boolean); 
void SetModal (Boolean fModal); 

Specify whether a window is modal. If fModal is TRUE, the window is 
modal. If fModal is FALSE, it is not modal. If a modal window is the front- 
most window, mouse clicks anywhere except in the window and in the 
menu bar are ignored. 

function IsColor: Boolean; 

Boolean IsColor (void); 

Return TRUE if this is a color window. 

procedure SetTitle (theTitle: Str255); 
void SetTitle (Str255 theTitle); 

Set the window’s title. 

procedure GetTitle (var theTitle: Str255); 
void GetTitle (Str255 theTitle); 

Get the window’s title. 

procedure SetActClick (anActClick: Boolean); 
void SetActClick (Boolean anActClick); 

If anActClick is TRUE, the window processes the mouse click that activat¬ 
ed it. 

function WantsActClick: Boolean; 

Boolean WantsActClick (void); 

Return TRUE if the window processes the mouse click that activates it. 
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Contains 


SetSIzeRect 


SetStdState 


SetHelpResID 


CetHelpResID 


Show 


Hide 


function Contains (thePoint: Point): Boolean; 

Boolean Contains (Point thePoint); 

Return TRUE if thePoint is inside the window. ThePoint is in global co¬ 
ordinates. 

procedure SetSizeRect (aSizeRect: Rect); 
void SetSizeRect (Rect *aSizeRect); 

Set the minimum and maximum size for the window. ASizeRecf s top,left 
are the minimum height and width. ASizeRect’s bottom,right are the max¬ 
imum. 

procedure SetStdState (aStdState: Rect); 
void SetStdState (Rect *aStdState); 

Set the standard state of a window. The standard state is the size and loca¬ 
tion of the window when it’s zoomed out. Before you send this message to a 
window, make sure that the Macintosh window associated with it supports 
zooming. If it does, the spareFlag in the window record is true. 

procedure SetHelpResID (aResID: integer); 
void SetHelpResID (short aResID); 

Set the resource ID of the ' href Balloon Help resource associated with this 
window. For more information about using Balloon Help with the THINK 
Class Library, see “Using Balloon Help with views” on page 436. 

function GetHelpResID: integer; 
short GetHelpResID (void); 

Get the resource ID of the ' hret' resource associated with this window. If 
you do not set one with SetHelpResID, helpResID is set to kDefault- 
HelpResID by default. 

Appearance methods 

procedure Show; 
void Show (void); 

Show a window. Also sends its enclosure (the desktop) a ShowWind mes¬ 
sage. 

procedure Hide; 
void Hide (void); 

Hide a window. Also sends its enclosure (the desktop) a HideWind mes¬ 
sage. 
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Activate 


Deactivate 


Select 


ShowResume 


HideSuspend 


ShowOrHide 


Drag 


procedure Activate; 
void Activate (void); 

Activate a window and all of its panes. Also sends its supervisor (a director) 
an ActivateWind message. 

procedure Deactivate; 
void Deactivate (void); 

Deactivate a window and all of its panes. Also sends its supervisor (a direc¬ 
tor) a DeactivateWind message. 

procedure Select; 
void Select (void); 

Select a window by bringing it to the front and making it active. Sends its en¬ 
closure (the desktop) a SelectWind message. 

procedure ShowResume; 
void ShowResume (void); 

Make a window visible when an application resumes. If you hide your win¬ 
dows when your application is suspended, send it this message in its direc¬ 
tor’s Resume method. 

procedure HideSuspend; 
void HideSuspend (void); 

Hide a window when an application is suspended. To hide a window when 
the application is being suspended, send the window this message in its di¬ 
rector’s Suspend method. The HideSuspend method doesn’t actually 
hide the window. Instead, it moves it out of the visible range so the front-to- 
back ordering of the windows doesn’t change. 

procedure ShowOrHide (showFlag: Boolean); 
void ShowOrHide (Boolean showFlag); 

Make a window visible or invisible without generating any update or acti¬ 
vate events. 

Size and location methods 

procedure Drag (macEvent: EventRecord); 
void Drag (EventRecord *macEvent); 

Drag a window. This method is invoked when the user clicks in a window’s 
drag region. The default method sends a DragWind message to the desk¬ 
top. 
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Resize 


Zoom 


Move 


ChangeSIze 


MoveOffScreen 


Update 


Prepare 


procedure Resize (macEvent: EventRecord); 
void Resize (EventRecord *macEvent); 

Resize a window. This method is invoked when you click and drag the win¬ 
dow’s grow region. After resizing, this method sends a Changesize mes¬ 
sage to the window. 

procedure Zoom (direction: integer); 
void Zoom (short direction); 

Zoom a window. This method is invoked when the user clicks in a window’s 
zoom box. Direction is either inZoomln or inZoomOut. After changing the 
size of the window, this method sends an AdjustToEnclosure message 
to its panes. 

procedure Move (hGlobal, vGlobal: integer); 
void Move (short hGlobal, short vGlobal); 

Move the window to the specified location in global coordinates. Note that 
the new position refers to the top left corner of the window’s content region. 
The title bar will be above the specified coordinates. 

procedure ChangeSize (width, height: integer); 
void ChangeSize (short width, short height); 

Change the size of the window to the specified width and height. After 
changing the window size, this method sends an AdjustToEnclosure 
message to its panes. This method respects the maximum and minimum 
window sizesyou set with SetSizeRect. 

procedure MoveOffScreen; 
void MoveOffScreen (void); 

Move the window out of the visible area of the desktop. 

Drawing methods 

procedure Update; 
void Update (void); 

Update the window. This method is invoked when the Switchboard process¬ 
es an update event. This method sends a Prepare message to the window 
and then sends a Draw message to each of the window’s panes. You should 
not override this method. 

procedure Prepare; 
void Prepare (void); 

Set the port of the window and prepare for drawing. 
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DispatchClick 


DispatchCursor 


FrameToGlobaIR 


Mouse methods 

procedure DispatchClick (var macEvent: EventRecord); 
void DispatchClick (EventRecord *macEvent); 

Find a pane to handle the mouse click. You should not use or override this 
method. If you want to handle a click in a particular window subclass, over¬ 
ride the DoClick method (inherited from CView) instead. 

procedure DispatchCursor (where: Point; 
mouseRgn: RgnHandle); 

void DispatchCursor (Point where, RgnHandle mouseRgn); 
Find a pane that handles Ad just Cursor messages. This method converts 
where from global to window coordinates, and then lets the Dispatch¬ 
Cursor method in CView take care of displaying Balloon Help it if is en¬ 
abled. You should not use or override this method. 

Conversion methods 

procedure FrameToGlobaIR (frameRect: LongRect; 
globalRect: Rect); 

void FrameToGlobaIR (LongRect *frameRect, 

Rect *globalRect); 

Convert frameRect from frame to global coordinates. Place the result in 
globalRect. 
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DrawSICN 


TCL Library 
Routines t 
71 


Introduction 

The THINK Class Libary uses some library routines to deal with the Macin¬ 
tosh Tolbox, long coordinates, and memory allocation. The Starter seed 
projects are set up so you can use these utility routines. 

For a detailed description of the exception handling mechanism, see Chap¬ 
ter 8, “Exception Handling.” 

For more information about memory management, see “Handling low mem¬ 
ory situations” on page 138. 

Toolbox Utilities 

These routines make working with parts of the Macintosh Toolbox easier. 

THINK C programmers 

These functions are defined in TBUtilit ies . c. Be sure to include TBU- 
tilities.h before you use these functions. 

THINK Pascal programmers 

These routines are defined in TCL. p. 

QuickDraw Utilities 

procedure DrawSICN (SICNid, index: integer; 
location: Point); 

void DrawSICN (short SICNid, short index. 

Point location); 

Draw a small icon at the point location. SICNid is the resource id of a 
SICN resource. Index is the number of the small icon within the resource. 
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PinlnRect 


BringBehind 


IsDIalogWindow 

Is My Window 

IsMyWindow 

FindDlogPosition 


procedure PinlnRect (theRect: LongRect; 
var thePoint: LongPt); 

void PinlnRect (LongRect *theRect, Point *thePoint); 

Pin thePoint within theRect. This routine is similar to the Toolbox rou¬ 
tine PinRect except that the point is changed in place, and this routine 
does not subtract 1 at the right and bottom edges. 

Window Manager Utilities 

procedure BringBehind (macWindow, 
behindWindow: WindowPtr); 

void BringBehind (WindowPtr macWindow, 

WindowPtr behindWindow); 

BringBehind moves macWindow so it is behind behindWindow. The 
CFWDesktop class uses this routine to place the frontmost application win¬ 
dow behind all the floating windows. 

function IsDialogWindow (macWindow: WindowPeek): 
Boolean; 

Boolean IsDialogWindow (WindowPeek macWindow); 

Return TRUE if macWindow is a dialog window. 

function IsMyWindow (macWindow: WindowPeek): 

Boolean); 

Boolean IsMyWindow (WindowPeek macWindow); 

Returns TRUE if macWindow is an application window or a dialog window. 

function IsSystemWindow (macWindow: WindowPeek): 
Boolean); 

Boolean IsSystemWindow (WindowPeek macWindow); 

Returns TRUE if macWindow is a system window (desk accessory window). 

Dialog Manager Utilities 

procedure FindDlogPosition (theType: ResType; 
thelD: integer; var corner: Point); 

void FindDlogPosition (ResType theType, short thelD, 
Point *corner); 

Return in corner the coordinates of the upper left corner of the dialog or 
an alert if the dialog were centered in the upper third of the screen. This rou¬ 
tine is useful for the standard file dialogs which ask you to supply a corner 
point. Otherwise, you should use PositionDialog. 
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PosistionDlalog 


CetFontNumber 


KeylsDown 


AbortlnQueue 


IsCancelEvent 


ConcatPStrings 


procedure PositionDialog (theType: ResType; 
thelD: integer); 

void PositionDialog (ResType theType, short thelD); 
Center the bounding box of a dialog or an alert in the upper third of the 
screen. TheType is either 'DUDC or 1 ALRT * and the ID is the resource 
ID of the dialog or the alert. PositionDialog does not display the dialog, 
it just changes its location. 

Font Manager Utility 

procedure GetFontNumber (fontName: ConstStr255Param; 
var fontNum: integer); 

void GetFontNumber (ConstStr255Param fontName, 
short *fontNum); 

Given a font name, return its font number in fontNum If the font is not 
found, return a negative number. 

Keyboard Utilities 

function KeylsDown (theKeyCode: integer): Boolean; 
Boolean KeylsDown (short theKeyCode); 

Return TRUE if the specifed key is being held down. Note that the key code 
is depends on the kind of keyboard. This function does not tell you if a spe¬ 
cific key character is being held down. 

function AbortlnQueue: Boolean; 

Boolean AbortlnQueue (void); 

Return TRUE if there is a Command-Period pending in the event queue. If 
there is, the event is removed from the queue. 

function IsCancelEvent (anEvent: EventRecord): 

Boolean; 

Boolean IsCancelEvent (EventRecord *anEvent); 

Return TRUE if anEvent is a “cancel” event. In US keyboards, a cancel event 
is Command-Period. For more information about cancelling in international 
environments, see Tech Note 263. 

String Utilities 

C only 

void ConcatPString (Str255 first, 

ConstStr255Param second); 

Concatenate two Pascal strings. The string second is added to the end of 
first. The result is truncated if it would be longer than 255 bytes. Pascal 
programmers should use the built-in procedure concat. 
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CopyPStrlng Conly 

void CopyPString (ConstStr255Param srcString, 

Str255 destString); 

Copy srcString into desString. The original contents of destString 
are lost. Pascal programmers should assign one string to another. 

Operating System Utilities 

THINK C programmers 

These functions are defined in OSChecks . c. Be sure to include 
OS Checks . h before you use these functions. 

THINK Pascal programmers 

These routines are defined in TCL. p. 

TrapAvallable function TrapAvailable (trapNum: integer) : Boolean; 

Boolean TrapAvailable (short trapNum) ; 

Return TRUE if the specified trap is available. 

WNEIsImplemented function WNE Is Implemented: Boolean; 

Boolean WNEIsImplemented (void); 

Return TRUE if the WaitNextEvent is available. WaitNextEvent is 
availble in every system from System 6.0. 

TempMemCaHsAvailable function TemMemCallsAvailable : Boolean; 

Boolean TemMemCallsAvailable (void); 

Return TRUE if the MultiFinder temporary memory calls are available. 

ColorQDIsPresent function ColorQDIsPresent: Boolean; 

Boolean ColorQDIsPresent (void); 

Return TRUE if Color QuickDraw is available. 

Long Coordinate Utilities 

These routines operate on long rectangles and long points. These routines 
do not map long points from frame coordinates to QuickDraw coordinates 
or vice versa. To map frame coordinates to QuickDraw coordinates, use the 
transformation methods in CPane. See “Coordinate transformation methods” 
on page 331. 
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QDToLongPt 


LongToQDPt 


SetLongPt 


AddLongPt 


SubLongPt 


EqualLongPt 


♦ 

THINK C programmers 

These functions are defined in LongCoordinates . c. Be sure to include 
LongCoordinates . h before you use these functions. 

THINK Pascal programmers 

These functions are defined in TCL . p. 

Long point utilities 

procedure QDToLongPt (srcPt: Point; 
var destPt: LongPt); 

void QDToLongPt (Point srcPt, LongPt *destPt); 

Convert srcPt from a QuickDraw point to a long point and place the result 
in destPt. 

procedure LongToQDPt (srcPt: LongPt; 
var destPt: Point); 

void LongToQDPt (LongPt *srcPt, Point *destPt); 

Convert srcPt from a long point to a QuickDraw point and place the result 
in destPt. If srcPt is not in QuickDraw space, it is clipped to 16 bits. To 
convert a long point in frame coordinates to a QuickDraw point, use CPane’s 
FrameToQD method. 

procedure SetLongPt (var pt: LongPt; h, v: longint); 
void SetLongPt (LongPt *pt, long h, long v); 

Set the horizontal and vertical elements of long point pt to h and v. 

procedure AddLongPt (srcPt: LongPt; 
var destPt: LongPt); 

void AddLongPt (LongPt *srcPt, LongPt *destPt); 

Add srcPt and destPt and return the result in destPt. 

procedure SubLongPt (srcPt: LongPt; 
var destPt: LongPt); 

void SubLongPt (LongPt *srcPt, LongPt *destPt); 

Subtract srcPt from destPt and return the result in destPt. 

function EqualLongPt (ptl: LongPt; 
pt2: LongPt): Boolean; 

Boolean EqualLongPt (LongPt *ptl, LongPt *pt2); 

Return TRUE if pt 1 and pt 2 are the same point. 
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PtlnQD Space 

QDToLongRect 

LongToQDRect 

SetLongRect 

OffsetLongRect 

InsetLongRect 

SectLongRect 


function PtlnQSpace (pt: LongPt): Boolean; 

Boolean PtlnQSpace (LongPt *pt); 

Return TRUE if pt is within 16-bit QuickDraw coordinate space. 

Long rectangle utilities 

procedure QDToLongRect (srcRect: Rect; 
var destRect: LongRect); 

void QDToLongRect (Rect *srcRect, LongRect *destRect); 

Convert srcRect from a QuickDraw rectangle to a long rectangle and re¬ 
turn the result in destRect. 

procedure LongToQDRect (srcRect: LongRect; 
var destRect: Rect); 

void LongToQDRect (LongRect *srcRect, Rect *destRect); 
Convert srcRect from a long rectangle to a QuickDraw rectangle and re¬ 
turn the result in destRect. 

procedure SetLongRect (var r: LongRect; left, top, 
right, bottom: longint); 

void SetLongRect (LongRect *r, long left, long top, 
long right, long bottom); 

Set the elements of the long rectangle r. 

procedure OffsetLongRect (var r: LongRect; dh, dv: 
longint); 

void OffsetLongRect (LongRect *r, long dh, long dv); 
Offset r by dh and dv. Positive values are to the right and down. 

procedure InsetLongRect (var r: LongRect; 
dh, dv: longint); 

void InsetLongRect (LongRect *r, long dh, long dv); 
Inset the sides of r by dh and dv. Positive values move the sides in. 

function SectLongRect (srcl, src2: LongRect; 
var destRect: LongRect): Boolean; 

Boolean SectLongRect (LongRect *srcl, LongRect *src2, 
LongRect *destRect); 

Calculate the intersection of srcl and src2, and place the result in 
destRect. DestRect maybe the same as srcl or src2. If destRect is 
not empy, return TRUE. 
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PtlnLongRect 


Pt2LongRect 


EqualLongRect 


EmptyLongRect 


RectlnQDSpace 
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procedure UnionLongRect (srcl, src2: LongRect; 
var destRect: LongRect); 

void UnionLongRect (LongRect *srcl, LongRect *src2, 
LongRect *destRect); 

Calculate the union of srcl and src2, and place the result in destRect. 
DestRect may be the same as srcl or src2. 

function PtlnLongRect (pt: LongPt; 
r: LongRect): Boolean; 

Boolean PtlnLongRect (LongPt *pt, LongRect *r); 

Return TRUE if the long point pt is in the long rectangle r. 

procedure Pt2LongRect (ptl, pt2: LongPt; 
var r: LongRect); 

void UnionLongRect (LongPt *ptl, LongPt *pt2, 

LongRect *r); 

Calculate the smallest rectangle that encloses ptl and pt2 and return the 
result in the long rectangle r. 

function EqualLongRect (rl, r2: LongRect): Boolean; 
Boolean EqualLongRect (LongRect *rl, LongRect *rl) ; 
Return TRUE if the long rectangles r 1 and r2 are identical. 

function EmptyLongRect (r: LongRect): Boolean; 

Boolean EmptyLongRect (LongRect *r); 

Return TRUE if the long rectangle r encloses no points. 

function RectlnQDSpace (r: LongRect): Boolean; 

Boolean RectlnQDSpace (LongRect *r); 

Return TRUE if the long rectangle r is .entirely within QuickDraw space. 

THINK Class Library Utilities 

These routines are generally useful for working with the THINK Class Li¬ 
brary. Some of them work with the exception handling mechanism (see 
Chapter 8, “Exception Handling”) and with the memory management rou¬ 
tines (see “Handling low memory situations” on page 138). 

THINK C programmers 

These functions are defined in TCLUtilities . c. Be sure to include 
TCLUtilities.h before you use these functions. 
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ErrorAlert 


NewHandleCanFail 


ResizeHandleCanFail 


SetAllocation 


THINK Pascal programmers 

These routines are defined in TCL. p. EqualMem is written in assembly lan¬ 
guage. It is defined in TCL. lib. 

Error reporting utility 

procedure ErrorAlert (error: integer; 
message: longint); 

void ErrorAlert (short error, long message); 

Display an alert for the given error and message codes. If the low word 
of message is zero, ErrorAlert looks for an 'Estr 1 resource that match¬ 
es the error code in error. If it can’t find one, it displays a generic error 
message and the error number. 

If the low word of message is greater than zero, it is used as an index into a 
1 STR# * resource. If the high word of message is zero, ErrorAlert uses 
the resource 1 STR# 1 3 01 . If the high word of mes s age is not zero, its val¬ 
ue is added to 1024 to get the resource ID of a ' STR# 1 resource. You can 
use the exception handler’s Specif yMsg function to build the message. 

For instance, if message is 655,363—0x0 0 0 AO 0 0 3 hex—, the resource ID of 
the ' STR# ' resource is 1024+10, and the index into it is 3. 

If the application is running, ErrorAlert uses ' ALRT ' ALRT_Excep- 
tion (251), otherwise it uses 'ALRT ' ALRT_ExceptionAbort (252). 

Memory allocation utilities 

function NewHandleCanFail (size: longint): Handle; 
void *NewHandleCanFail (long size); 

Allocate a handle without drawing on the memory reserve. If the allocation 
fails, returns NIL. 

procedure ResizeHandleCanFail (theHandle: Handle; 
newSize: longint); 

void ResizeHandleCanFail (void *theHandle, long 
newSize); 

Resize a handle without drawing on the memory reserve. 

function SetAllocation (canFail: Boolean): Boolean; 
Boolean SetAllocation( Boolean canFail); 

Change the parameters that gApplication uses when the grow zone 
function is invoked because the memory manager can’t satisfy a request. If 
canFail is TRUE (or kAllocCanFail), memory requests are allowed to 
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SetCriticalOperation 
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fail without drawing on memory reserves. If canFail is FALSE (or 
kAllocCantFail), the application will try to satisfy the memory request 
from the reserves. Set Allocation returns the previous setting. You 
should reset the allocation parameters after you make a memory request. 

In THINK C, you might do it like this: 

void AClass::AMethod(void) 

{ 

Boolean oldAlloc; 

oldAlloc = SetAllocation(kAllocCanFail); 

request memory here 
SetAllocation(oldAlloc); 

fail gracefully if it doesn Y succeed 

} 

In THINK Pascal, you could do it this way: 

procedure AClass.AMethod; 
var 

oldAlloc: Boolean; 
begin 

oldAlloc := SetAllocation(kAllocCanFail); 
request memory here 

oldAlloc := SetAllocation(oldAlloc); 
fail gracefully if it doesn Y succeed 

end; 

This method sends a RequestMemory method to gApplication. See 
“Handling low memory situations” on page 138 for more information about 
working with memory in the THINK Class Library. 

procedure SetCriticalOperation (aCriticalOp: Boolean); 
void SetCriticalOperation (Boolean aCriticalOp); 

Change the parameters that gApplication uses when the grow zone 
function is invoked because the memory manager can’t satisfy a request. If 
aCriticalOp is TRUE, more of the memory reserve is available to satisfy a 
failing memory request. 

This method sends a SetCriticalOperation message to gApplica¬ 
tion. See “Handling low memory situations” on page 138 for more infor¬ 
mation about working with memory in the THINK Class Library. 
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EqualMem 


SetMinimumStack 


ForgetHandle 


ForgetPtr 


ForgetResource 


ForgetObject 


function EqualMem (pi, p2: Ptr; n: longint): Boolean; 
Boolean EqualMem (void *pl, void *p2, long n); 

Compare two blocks of memory, and return TRUE if they are equal. PI and 
p2 point to memory, and n is the number of bytes to compare. 

procedure SetMinimumStack (newSize: minSize); 
void SetMinimumStack (long minSize); 

Set the stack to be at least minSize bytes. If you use this routine, it must ap¬ 
pear only once, and it must be the first statement in your program. 

Memory disposal utilities 

These memory utilities release different kinds of memory, and set the vari¬ 
able that references them to NIL. In THINK C, these routines are implement¬ 
ed as macros, which are defined in Global. h. In THINK Pascal they’re 
defined as procedures in TCL. p. 

procedure ForgetHandle (var handle: Handle); 
void ForgetHandle (Handle h); [MACRO] 

If h is not NIL, call DisposHandle (h), and set h to NIL. 

procedure ForgetPtr (var p: Ptr); 
void ForgetPtr (Ptr p); [MACRO] 

If p is not NIL, call DisposPtr (p), and set p to NIL. 

procedure ForgetResource (var r: Handle); 
void ForgetResource (Handle r); [MACRO] 

If r is not NIL, call ReleaseResource (r), and set r to NIL. 

procedure ForgetObject (var obj: CObject); 
void ForgetObject (CObject obj); [MACRO] 

If obj is not NIL, send obj a Dispose or Free message, and set obj to 
NIL. 

Long Coordinate QuickDraw Utilities 

The following routines are long coordinate versions of some common 
QuickDraw routines. The arguments that these routines take are long points 
and long rectangles in frame coordinates. If you use these routines, be sure 
that you call them only in a pane’s Draw method because they expect that 
the pane has already been prepared. 
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LEraseRect 


LFrameRect 


LlnvertRect 


LPaintRect 


LFillRect 


LEraseOval 


Note - 

These routines transform frame coordinates to QuickDraw 
coordinates every time you call them. It’s usually more con¬ 
venient to do the transformation once, then do all the 
drawing in QuickDraw coordinates. 

THINK C programmers 

These functions are defined in LongQD. c. Be sure to include LongQD . h 
before you use these functions. 

THINK Pascal programmers 

These routines are defined in LongQD . p. 

Long rectangle drawing routines 

procedure LEraseRect (area: LongRect); 
void LEraseRect (LongRect *area); 

Erase the rectangle specified in area. 

procedure LFrameRect (area: LongRect); 
void LFrameRect (LongRect *area); 

Frames the rectangle specified in area. 

procedure LlnvertRect (area: LongRect); 
void LlnvertRect (LongRect *area); 

Invert the rectangle specified in area. 

procedure LPaintRect (area: LongRect); 
void LPaintRect (LongRect *area); 

Paint area in the current pattern and mode. 

procedure LFillRect (area: LongRect; pat: Pattern); 
void LFillRect (LongRect *area. Pattern pat); 

Fill area in the pattern pat in pat Copy mode. 

Long oval drawing routines 

procedure LEraseOval (area: LongRect); 
void LEraseOval (LongRect *area); 

Erase the oval specified in area. 
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LFrameOval 


LlnvertOval 


LPaintOval 


LFillOval 


LEraseRoundRect 


LFrameRoundRect 


LlnvertRoundRect 


LPaintRoundRect 


procedure LFrameOval (area: LongRect); 

void LFrameOval (LongRect *area); 

Erase the oval specified in area. 

procedure LlnvertOval (area: LongRect); 

void LlnvertOval (LongRect *area); 

Invert the oval specified in area. 

procedure LPaintOval (area: LongRect); 

void LPaintOval (LongRect *area); 

Paint area in the current pattern and mode. 

procedure LFillOval (area: LongRect; pat: Pattern); 

void LFillOval (LongRect *area, Pattern pat); 

Fill area in the pattern pat in patCopy mode. 

Long rounded rectangle drawing routines 

procedure LEraseRoundRect (area: LongRect; 
ovWidth, ovHeight: integer); 

void LEraseRoundRect (LongRect *area, 
short ovWidth, short ovHeight); 

Erase the rounded rectangle specified in area. 

procedure LFrameRoundRect (area: LongRect; 
ovWidth, ovHeight: integer); 

void LFrameRoundRect (LongRect *area, 
short ovWidth, short ovHeight); 

Erase the rounded rectangle specified in area. 

procedure LlnvertRoundRect (area: LongRect; 
ovWidth, ovHeight: integer); 

void LlnvertRoundRect (LongRect *area, 
short ovWidth, short ovHeight); 

Invert the rounded rectangle specified in area. 

procedure LPaintRoundRect (area: LongRect; 
ovWidth, ovHeight: integer); 

void LPaintRoundRect (LongRect *area, 
short ovWidth, short ovHeight); 

Paint area in the current pattern and mode. 
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LFillRoundRect 


LCopyBits 


LMoveTo 


LLineTo 


LRectRgn 


LClipRect 


procedure LFillRoundRect (area: LongRect; 

ovWidth, ovHeight: integer; pat: Pattern); 

void LFillRoundRect (LongRect *area, 

short ovWidth, short ovHeight, Pattern pat); 

Fill area in the pattern pat in patCopy mode. 

Long bit transfer routine 

procedure LCopyBits (srcBits, dstBits: BitMap; 
srcRect, dstRect: LongRect; 
mode: integer; mask: RgnHandle); 

void LCopyBits (BitMap *srcBits, BitMap *dstBits, 
LongRect *srcRect, LongRect *dstRect, 
short mode, RgnHandle mask); 

Transfer a bit image from srcBits to dstBits. For a full description of 
this routine, see the description of CopyBits in Inside Macintosh I. 

Long point pen routines 

procedure LMoveTo (hLoc, vLoc: longint); 
void LMoveTo (long hLoc, long vLoc); 

Move the pen to the point hLoc, vLoc. 

procedure LLineTo (hLoc, vLoc: longint); 
void LLineTo (long hLoc, long vLoc); 

Draw a line from the current pen location to hLoc, vLoc. 

Long region utility routines 

procedure LRectRgn (rgn: RgnHandle; rect: LongRect); 
void LRectRgn (RgnHandle rgn, LongRect *rect); 

Create a region whose shape is specified by rect. Rgn must be a handle to 
an existing region. 

procedure LClipRect (r: LongRect); 
void LClipRect (LongRect *r); 

Change the clipping region of the current grafPort to the long rectangle r. 
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gApplicatlon 


gDesktop 


gBartender 


Introduction 

This chapter describes the global variables in the THINK Class Library. 

Global Objects 

These globals hold pointers to the only instances of some classes. Most of 
them are initialized in the application initialization routines. You should not 
need to reset any of these variables yourself, except for gSleepTime. 

gApplication: CApplication; 

CApplication *gApplication; 

The global application object. You should set this variable to an instance of 
your application class in your main program. See “Writing the main pro¬ 
gram” in CApplication on page 137 for an example. 

gDesktop: CDesktop; 

CDesktop *gDesktop; 

The desktop. This variable holds the only instance of CDesktop (or 
CFWDesktop if you’re using floating windows). It’s initialized in the applica¬ 
tion method MakeDesktop. The desktop is the enclosure for all the 
windows in your application. It is the top of the visual hierarchy. 

gBartender: CBartender; 

CBartender *gBartender; 

The bartender. This variable holds the only instance of CBartender. It’s ini¬ 
tialized in the application method SetUpMenus. The bartender converts 
menu choices into command numbers and handles most menu operations. 
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gClipboard 


gCopher 


gError 


g Decorator 


g LastMouseDown 


gLastMousellp 


gLastViewHit 


gClipboard: CClipboard; 

CClipbard *gClipboard; 

The clipboard. This variable holds the only instance of CClipboard. It’s ini¬ 
tialized in the application method MakeClipboard. The clipboard is 
where data is cut and copied to and pasted from. 

gGopher: CBureaucrat; 

Cbureaucrat *gGopher; 

The gopher is the first bureaucrat to get commands. I f the gopher can’t han¬ 
dle the command, it passes control to its supervisor. Initially, the gopher is 
set to the application (gApplicat ion). When a document becomes active, 
the gopher points to the document. A document can set the gopher to point 
to one of its panes. 

gError: CError; 

CError *gError; 

The global error handler. This variable is initialized in I Application. 

gDecorator: CDecorator; 

CDecorator *gDecorator; 

The window dresser. This variable holds the only instance of CDecorator. It’s 
initialized in the application method MakeDecorator. The decorator takes 
care of arranging windows on the screen. 

Mouse Click Globals 

The THINK Class Library uses these globals to count mouse clicks. The only 
variable you’ll need to use is gC licks. 

gLastMouseDown: EventRecord; 

EventRecord gLastMouseDown; 

Event record of the last mouse-down event. 

gLastMouseUp: EventRecord; 

EventRecord gLastMouseUp; 

Event record of the last mouse-up event. 

gLastViewHit: CView; 

CView *gLastViewHit; 

The last view the mouse went down in. 
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gClicks 


gIBeamCursor 


gWatchCursor 


g System 


- ♦ 


gClicks: integer; 
short gClicks; 

Click counter. This variables counts multiple clicks. Its value is 1 for a single 
click, 2 for a double click, 3 for a triple click, etc. To be considered a multiple 
click the mouse must go down in the same view as the last mouse down 
within the amount of time specified by GetDblTime and the view method 
Hit Same Part must return TRUE. 

Cursors 

These cursor handles are initialized in IApplication. You can use them 
as arguments to SetCursor. Remember that these are handles, so you’ll 
have to call SetCursor like this in THINK Pascal: 

SetCursor(gWatchCursor A ) ; 

And like this in THINK C: 

SetCursor(*gWatchCursor) ; 

gIBeamCursor: CursHandle; 

CursHandle gIBeamCursor; 

I-beam for text views. 

gWatchCursor: CursHandle; 

CursHandle gWatchCursor; 

Watch cursor for waiting. 

System Globals 

You can use these globals to get information about the environment that 
your application is running in, and about the state of your application. 

gSystem: tSystem; 
tSystem gSystem; 

This global is a record that contains fields that tell you about the capabilities 
of Macintosh that your program is running under. It’s initialized in the 
Inspect System method of CApplication. 
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In THINK C, tSystem is declared like this: 

typedef struct 

{ 

Boolean hasWNE : 1; 

Boolean hasColorQD : 1; 

Boolean hasGestalt : 1; 

Boolean hasAppleEvents : 1; 

Boolean hasAliasMgr : 1; 

Boolean hasEditionMgr : 1; 

Boolean hasHelpMgr : 1; 

Boolean hasScriptMgr : 1; 

Boolean hasFPU : 1; 

short scriptslnstalled; 

short systemVersion; 

} tSystem; 

In THINK Pascal it’s defined like this: 
type 

tSystem = packed record of 
hasWNE, 
hasColorQD, 
hasGestalt, 
hasAppleEvents, 
hasAliasMgr, 
hasEditionMgr, 
hasHelpMgr, 
hasScriptMgr, 

hasFPU : Boolean; 

scriptslnstalled, 
systemVersion : integer; 

end; 

The field scriptslnstalled tells you how many scripts are in use. The 
field systemVersion gives you the version of the Macintosh System that’s 
running. The version number is given as two byte-long numbers. For exam¬ 
ple, if systemVersion is 0x0 607, the System version number is 6.0.7. 

gSleepTIme gSleepTime: longint; 

long gSleepTime; 

The switchboard uses this value to pass to WaitNextEvent. It is the maxi¬ 
mum time (in ticks) between events. Perform methods in CChore subclasses 
and Dawdle methods in CBureaucrat subclasses can change this value indi¬ 
rectly to force an idle event. 
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glnBackground 


gLastError 


gLastMessage 


gSignature 


gUtiIRgn 


---- 4 

glnBackground: Boolean; 

Boolean glnBackground; 

TRUE if the application is in the background. 

Error Globals 

These global variables let you see what error raised the last exception. The 
values of these variables is valid only within a catch handler. At any other 
time, they’re undefined. For more information about exception handling, 
see Chapter 8, “Exception Handling.” 

gLastError: integer; 
short gSignature; 

The error that raised an exception. 

gLastMesage: longint; 
long gLastMessage; 

The message passed to Failure at the last exception. 

Utility Globals 

gSignature: OSType; 

OSType gSignature; 

The signature of your application. You should initialize this variable in your 
SetUpFileParameters application method. Use this variable whenever 
your application needs to create a file. 

gUtiIRgn: RgnHandle; 

RgnHandle gUtiIRgn; 

Utility region. This region is initialized with NewRgn in lApplication. 

You can use it wherever you need a region, but you should not rely on it be¬ 
ing the same across calls to different methods. 


Warning 

If you use gUtiIRgn, be sure that you never dispose of it. 
If you’ve created a complex region, and you want to re¬ 
lease some memory, use SetEmptyRgn to make it as small 
as possible. 
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MacApp and 
THINK Pascal * 

A 


T 


his appendix tells you what you need to know to use Apple’s MacApp with 
THINK Pascal. MacApp was written specifically for Apple’s Macintosh Pro¬ 
grammer’s Workshop (MPW) and, it takes advantage of some idiosyncrasies 
and features of that environment and its MPW Pascal compiler. To use 
MacApp with THINK Pascal, you need to modify some of the MacApp files. 


Note 

THINK Pascal 4.0 only supports MacApp 2.0.1 and MacApp 
2.0.2. Make sure that you have the correct version of 
MacApp from Apple. 
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What is MacApp? ^ 


What is MacApp? 

MacApp is a collection of classes that help you build a Macintosh applica¬ 
tion. MacApp is available directly from Apple through APDA. You don’t 
need to use MacApp to build Macintosh applications with THINK Pascal. 
The THINK Class Library included with your THINK Pascal package is an al¬ 
ternative class library that you can use as the foundation for your applica¬ 
tions. 


Note 

THINK Pascal 4.0 only supports MacApp 2.0.1 and MacApp 
2.0.2. Make sure that you have the correct version of 
MacApp from Apple. 


Before you begin 

Make sure that you’ve installed THINK Pascal according to the instructions 
in Chapter 2 of your THINK Pascal User Manual. You don’t need to install 
the THINK Class Library to use MacApp. 

Make sure that you’ve installed MacApp according to the instructions in your 
MacApp documentation. You should have a folder called MacApp some¬ 
where on your disk. If you’re using MPW, this folder should be in your MPW 
folder. If not, the MacApp folder can be anywhere on your disk that’s conve¬ 
nient for you. 

If you don’t use MPW, these are the general instructions for installing 
MacApp: 

1. Create a folder called MacApp 

2. Copy the contents of all the MacApp disks to the MacApp folder. 

3. Combine the contents of all folders named things like More 
Thing, Even More Thing, Even More Thing\ into one folder 
called Thing 

Even though the converter doesn’t alter your original MacApp source files, 
be sure that you have a backup copy of your entire MacApp package. 

Take your time 

Installing and setting up the files that you need to use MacApp with THINK 
Pascal will take a couple of hours. You’ll be copying files from your THINK 
Pascal package, moving files from your original MacApp package, convert¬ 
ing the MacApp sources, and building seed projects for THINK Pascal. Take 
your time to make sure you do everything right. 
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Minimum Requirements 

To use MacApp with THINK Pascal, you need a Macintosh with at least 4 
megabytes of RAM. You need a hard disk with at least 2 megabytes for 
MacApp and 1 megabyte per built project. If you want to keep your original 
copy of MacApp on disk, you’ll need another 2 megabytes. 

Memory Requirements 

MacApp takes up quite a bit of memory. To make the best use of MacApp, 
you need at least 4Mb or RAM. You should set the zone size in the Run Op¬ 
tions... dialog of the Run menu to be at least 1536K. You should set the 
stack size to be 32K, though you may be able to use as little as 16K. 

Running MacApp with MultlFInder 

If you’re using System 6.0, you may want to not run under MultiFinder be¬ 
cause MacApp with THINK Pascal takes up so much memory. If you do 
want to run with MultiFinder or System 7.0, be sure that you make the 
THINK Pascal partition size about 3072K or larger. 

Running MacApp with the Finder 

When you use THINK Pascal with the Finder, it will use as much memory as 
there is on your Macintosh (except for what’s in the System heap). 

Compatibility 

Since both THINK Pascal and MacApp intercept several Toolbox traps, you’ll 
have an easier time if you remove as many non-essential INITs as possible. 
Removing INITs not only frees up memory, it also ensures that you’re run¬ 
ning in a clean environment. 

Installing MacApp Files for THINK Pascal 

Your THINK Pascal package includes several Files that you need to make 
MacApp work with THINK Pascal. These files include the Pascal Source 
Converter, which converts the MacApp sources so they’re compatible with 
THINK Pascal, and prebuilt projects for a generic MacApp application and 
the example programs that come with MacApp. All of these Files are com¬ 
pressed in the File called MacApp 2.0 for THINK Pascal.sea. 

To install these Files on your disk, double-click on the file MacApp 2.0 
for THINK Pascal. sea. When you’re asked for a folder to extract to, 
choose the Development folder that you installed THINK Pascal into. 

When the installation is complete, there should be a folder called THINK 
MacApp in your in your THINK Pascal 4.0 Folder and a folder called 
MacApp 2.0 for THINK Pascal 4.0 in your Development folder. 
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The MacApp 2.0 for THINK Pascal 4.0 folder contains these files 
and folders: 


File or Folder 

Pascal Source Converter 


Generic.Script 


MacApp Seeds 


MacApp.Script 


•Samples From MacApp* 


Description 

An application that converts MPW 
Pascal programs into THINK Pas¬ 
cal programs. 

A script for the Pascal Source con¬ 
verter that converts MPW Pascal 
source files into THINK Pascal 
source files. 

A set of pre-segmented MacApp 
projects ready for you to add your 
own files. You’ll uses these 
projects as the seeds for all your 
MacApp projects. 

A script for the Pascal Source 
Converter that converts MacApp 
2.0.1 or MacApp 2.0.2 into a form 
that THINK Pascal can use. 

A set of projects for the MacApp 
sample programs. 


The Pascal Source Converter converts your MacApp sources so they’re com¬ 
patible with THINK Pascal. The MacApp. Script is a file that the converter 
uses to convert the files. The converter places the converted source files in 
folders within the THINK MacApp folder which is in the THINK Pascal 
4.0 Folder. 


Warning 

Don’t change the organization of the THINK MacApp fold¬ 
er or the MacApp 2.0 for THINK Pascal 4.0 folder 
until after you have converted your MacApp sources. 
MacApp. Script relies on this folder organization. 


Next, you need to copy some files from your original MacApp package to 
the THINK MacApp folder. These files are used to build the resource files 
that MacApp needs. The main reason for copying them to the THINK 
MacApp folder is to make them more convenient. 

Copy the folder RIncludes from the Interfaces folder in the original 
MacApp distribution disks to your THINK MacApp folder. 
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Everything is in place, and now you’re ready to convert the MacApp sources. 

Converting MacApp 

This section tells you how to use Pascal Source Converter to make your 
MacApp sources work with THINK Pascal. The converter is an application 
that modifies source files written for MPW Pascal so they’re compatible with 
THINK Pascal. It uses the script MacApp. Script to convert the MacApp 
sources. 

What the Pascal Source Converter does 

The Pascal Source Converter changes the MacApp sources so they don’t 
need to rely on features specific to MPW Pascal. For instance, it processes 
the MPW Pascal $ INCLUDE directive to either include a file or to replace it 
with a unit name in a USES clause. It turns MPW Pascal compiler directives 
into equivalent THINK Pascal compiler directives. The converter also splits 
up the file UMacApp . p into several units according to classes. 

You can use the Pascal Source Converter to convert your own programs that 
you’ve written for MPW. To learn how to use the Pascal Source Converter, 
see Chapter 20 of your THINK Pascal User Manual. 

Make sure you have enough disk space 

The converter needs around two megabytes of free disk space to work. After 
you convert your MacApp files, you can remove the original files from your 
disk. 

Convert MacApp 

To begin, double-click on the file MacApp. Script. This is what the file’s 
icon looks like in the Finder: 




Figure A-1 The MacApp.Script icon 
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Converting MacApp 

The source converter asks you to find the folder that contains the original 
MacApp sources: 


Which folder contains the MacRpp sources? 
€1 Macflpp I 


Examples 


CD Interfaces 
Q Libraries 
□ Tools 


Current Folder: 
“Macflpp” 

Selected Folder: 
“Examples” 



Figure A-2 Pascal Source Converter asking for original MacApp files 


This folder may be in your MPW folder. Select the folder and click on the 
Current or Selected button. The text next to each button tells you which fold¬ 
er the button selects. 


Note 

The Current button chooses the folder that you’re in—that 
is, the folder that’s displayed in the pop-up menu in the di¬ 
alog. The Selected button chooses the folder that’s high¬ 
lighted in the folder list. The prompts let you know which 
folder each button chooses. 


Next, the source converter asks you to find the THINK MacApp folder. The 
THINK MacApp folder should be in the THINK Pascal 4.0 Folder. 
This folder contains additional files that the converter uses to convert 
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MacApp for THINK Pascal. The converted MacApp files will end up in the 
THINK MacApp folder. 


Please select the THINK MacHpp Folder: 



“THINK Pascal 4.0 Folder” 


Selected Folder: 

“THINK MacHpp” 


Figure A-3 Pascal Source Converter asking for the THINK MacApp folder 

Use the Current or Selected button as before to choose the THINK MacApp 
folder. 

The Pascal Source Converter asks for one more folder, the • Samples From 
MacApp • folder. Find it on your disk and click on the Current or Selected 
button. 


[ Selected^] 
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From here on, the converter does all the work. Conversion takes five to ten 
minutes depending on the kind of Macintosh you’re using. As it’s converting 
the MacApp files, the converter displays a status window like this: 

Conuerting “UCards.p” 

(including UCards.incl.p) 

1751 lines processed, 830 lines total. 

4 files processed, 43 to go. 

Elapsed time: 0:25 

Ruerage Speed: 1992 lines per minute. 

Press 96-Period to cancel the conuersion. 


Figure A-4 Pascal Source Converter displaying status 

When it finishes converting the MacApp files, the converter displays an alert 
that tells you that it is done. 

Clean up 

Now that the converter is finished, you can delete some files to make more 
room on your hard disk. You can remove these two folders from the THINK 
MacApp folder: 

• Dif fs folder 

• Templates folder 

You can remove the file MacApp . Script from the THINK Pascal 
Folder. If you like, you can also delete the Pascal Source Converter from 
the THINK Pascal Folder, but you may want to use it to convert any ex¬ 
isting MPW Pascal source files. 
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Note 

To learn about the Pascal Source Converter in detail, see 
Chapter 20 in your THINK Pascal User Manual. 


If you don’t use MPW, and you need to make room on your hard disk, you 
can remove the original MacApp source files. You’ll probably want to keep 
the ViewEdit application and the . R and . Rsrc files from the Libraries 
folder. Be sure that the original MacApp files are backed up in a safe place. 

Building Your Seed Projects 

Now that you’ve converted the MacApp source files, you’re almost ready to 
use MacApp with THINK Pascal. The next thing you need to do is build your 
seed projects. The seed projects are prebuilt, precompiled, and preconfig¬ 
ured THINK Pascal projects that you use to build a MacApp-based applica¬ 
tion. 

Building the seed projects may take a couple of hours— particularly if you’re 
on a slower machine like a Macintosh Plus— but it will be time well spent. If 
you take time to build the seed projects now, you’ll save time in the future. 
Just as important as saving time, building the seed projects now will test that 
the conversion was completely successful. 

What's In the MacApp Seeds folder? 

The MacApp Seeds folder in the MacApp 2.0 for THINK Pascal 
4.0 folder contains four THINK Pascal projects and two resource files. The 
seed projects have all of the MacApp source files already added to them, and 
the project is segmented correctly. Only the options are different among all 
the projects. 

Since THINK Pascal needs to turn off the Debug option and recompile the 
entire project when you build your final application, you’ll save a lot of time 
if you build two projects. One project, MacApp .n has the Debug compiler 
option on for all files. This is the project you’ll use while you develop your 
application in the THINK Pascal environment. The other project, MacApp. - 
Build.TC has the Debug compiler option turned off. This is the project 
you’ll use when you’re ready to build the double-clickable final version of 
your application. 

If you plan to use MacApp’s built-in debugger, use the MacApp. Debug .n 
and MacApp. Build. Debug .n projects. MacApp. Debug. n is identical to 
MacApp. n except that it presets the compiler-variables that control whether 
to use the MacApp debugger. The MacApp. Build. Debug. n project is just 
like the MacApp. Build. n project, but with the debugger flags set. The 
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section “The compiler variables” below describes which compiler-variables 
are set in each project. 


Note ~ ’ 

The MacApp debugger is a set of classes and routines that 
let you examine existing objects while you’re program is 
running. Since the debugger is a part of your application, 
you can use the MacApp debugger in a built application. 


Here’s a summary of what each project is for: 


Used for... 

running in the THINK Pascal en¬ 
vironment without the MacApp 
debugger 

running in the THINK Pascal en¬ 
vironment with the MacApp 
debugger 

building a stand-alone applica¬ 
tion without the MacApp 
debugger 

MacApp. Build. Debug. n building a stand-alone applica¬ 

tion with the MacApp debugger 

The Build, Debug, and n suffixes are naming conventions that you may 
want to adopt. You don’t have to name your project this way. 

Build the projects 

To start building the seed projects, double-click on MacApp. n to open it. 
Next, choose the Build command from the Run menu. THINK Pascal starts 
building the project, loading libraries and compiling source files. This build 
will take about 45 minutes on a Macintosh Plus and about 15 minutes on a 
Macintosh Ilex. 


Project name 

MacApp .n 

MacApp.Debug. n 

MacApp.Build .n 


Note 

If you’re reading this at your machine, you might want to 
start building now, and keep reading while you wait. 


If THINK Pascal can’t find a file as it’s building the MacApp. n project, and 
you can’t find it manually, it probably means that something went wrong 
during the MacApp conversion. Make sure that you started with a complete 
set of the original MacApp source, and try the conversion again. 
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Warning 

Never try to run the . Build. n project under the environ¬ 
ment. It is only for building stand-alone applications. 


The compiler variables 

This table tells you which options are on for the different seed projects. A 
dash (-) means that the compile-time variable is set to 0, and a bullet (•) 
means that the compile-time variable is set to 1. 


Compile-time variable MacApp.Tt MacApp. 

Build.7t 

qDebug 

qWriteLnWin 

qTrace 

qRangecheck 

qNames • 

qTemplateViews • • 

qWWNeeded 

qProceduralViews • • 

qWriteTemplates • • 

qlnspector 
qUnlnit 

qDebugTheDebugger 

qNeedsHierarchialMenus 

qNeedsStyleTextEdit 

qNeedsWaitNextEvent 

qNeedsMC68020 

qNeedsMC68030 

qNeedsFPU 

qNeedsScriptManager 

qNeedsROM 128K 

qNeedsColorQD 

qMacApp • • 

qPerform 

qBusyCursor - • 

Table A-l MacApp compiler variables 


MacApp. MacApp. 
Debugs Debug.Build.7t 
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You may want to change some of these compiler variables in your project to 
suit the kind of application you’re writing. Your MacApp documentation ex¬ 
plains what these compiler variables are for. 

Segmentation 

MacApp sources sometimes make assumptions about how MacApp is seg¬ 
mented. You should not rearrange the segments in the seed projects unless 
you know what you’re doing. Be sure to follow Apple’s recommendations 
for segmenting your own MacApp-based program. 

Particularly make sure that you do not add any additional entries to the 
«%_MethTables» segment. You should also make sure that your main 
program is in the «Main» segment and that it is the first segment in the 
project. 


Note 

To learn how to segment your program in THINK Pascal, 
see Chapter 7 of your THINK Pascal User Manual. 


Using the Seed Projects 

Whenever you start a new MacApp-based program, copy the MacApp 
Seeds folder. Rename the folder and the projects inside the folder to the 
name of your program. You may or may not want to change the names of 
the resource files. 


Note 

If you change the names of the resource files, be sure to 
change the resource file setting in the Run Options... dia¬ 
log box. 


To use the seed projects, use the Add File... command to add your program 
files to the project. Since all of the MacApp files are already built, THINK 
Pascal will have to compile only the new files that you just added. 

To see how the seed projects work, make a duplicate of the four projects 
and drag them into one of the folders inside the • S amples F rom 
MacApp • folder. These folders contain the converted source code for the 
example programs that came with your original MacApp package. All you 
need to do is add the converted source files to the project and use the Run 
Options... command to set the resource file. 
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Note 

These folders already have resource files in them, so you 
don’t need to copy the MacApp. rs rc or MacApp .De¬ 
bug . rsrc resource files. 


Creating Resource Files for MacApp 

MacApp applications rely on several resources being present when you run 
them. When you use MacApp with MPW Pascal, you use the MPW tools Rez, 
DeRez, and PostRez to create these resource files from resource scripts 
called description files. Your THINK Pascal package comes with stand-alone 
versions of these applications called SARez, SADeRez, and SAPostRez. You 
can find these applications in the THINK Pascal Utilities folder. 
They’re described in detail in the THINK Pascal User Manual 

Using SARez 

MacApp uses different resources depending on whether you’re using the 
MacApp debugger. To have SARez create the correct resources for the 
MacApp debugger, you need to set certain symbols. Your THINK Pascal 
package includes two files that define the necessary symbols for both de¬ 
bugger and non-debugger versions of the resource files. The file Setting- 
s . R defines the symbols so Rez doesn’t produce these debugging resources. 
The file Debug .Sett ings . R sets the symbols so Rez produces the re¬ 
sources that the MacApp debugger needs. 

When you build your resource file in MPW, you fold in your application’s 
CODE resources with the other resources. In THINK Pascal, you use the Run 
Options... command to tell THINK Pascal which file contains the resources 
that project needs. If you’re working with an existing Rez resource descrip¬ 
tion file, you should remove any lines of the form: 

include $$Shell("ObjApp")"MyApplication" 'CODE'; 

THINK Pascal takes care of merging your application’s CODE resources with 
the other resources. 

Here are step-by-step instructions for creating a resource file for MacApp: 
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1 . Double-click on the SARez application to launch it. 

2. Click on the Resource Output file pop-up menu and choose the 
command that lets you create a new file. 

3. Give your resource file a name. You should make sure that the re¬ 
sulting resource file is in the same folder as your project. 

4. Set the new file’s type to ' rsrc ' and it's creator to ' RSED '. 

5. Check the Redeclared types OK check box. 

6. Click on the Description files button. This button lets you tell 
SARez where your resource description files are. 

7. If you’re not using the MacApp debugger, choose the file Set- 
t ings . R from the THINK MacApp folder. If you are using the 
MacApp debugger, choose the file Debug. Settings . R from 
the THINK MacApp folder. 

8. Choose the description files for your programs, the click on the 
Done button 

9. Click on the #include Paths button. This button lets you specify 
where SARez should look for #include files. 

10. Choose the RIncludes folder from the THINK Pascal 
Folder, the RIncludes folder from the THINK MacApp fold¬ 
er, and any addition directories that contain your own type de¬ 
scription files, then click Done. 

1 1 . Click on the Include Paths button. This button lets you specify 
where SARez should look for include files. 

12. If you’re not using the MacApp debugger, choose the Resourc¬ 
es folder in the THINK MacApp folder. Otherwise, choose the 
Debug Resources folder. If you have any precompiled re¬ 
source files to merge in to the compiled resource file, then 
choose the directories that contain those files. 

13. If you want to save the settings, choose the Save... command 
from the File menu. This command lets you save SARez settings 
in a file that you can open later. 

14. When everything is done, click the SARez button to start the com¬ 
pilation process. 

If the resource compilation is successful, launch SAPostRez tool to convert 
the cmnu resources into MENU and mntb resources. Double-click on SAPos¬ 
tRez, and choose the resource file you just created. 

Using the prebuilt resource files 

The MacApp Seeds folder contains two resource files: MacApp .rsrc and 
MacApp. Debug. Rs rc. These resource files contain the standard resources 
that you need to run programs with and without the MacApp debugger. 
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If you like, you can use these two resource files as the basis for your re¬ 
source files. Both of these files were built by merging the resources in either 
the Resources or Debug Resources folders in the THINK MacApp 
folder. 

Environment Differences 

When you run your application in the THINK Pascal environment, you’re 
not running in exactly the same kind of environment that your final applica¬ 
tion will run in. Though THINK Pascal does a good job of simulating an ap¬ 
plication environment, there are some things that you need to be aware of. 

Some of the differences arise because THINK Pascal needs to take some 
time away from your application so its debugging tools can monitor what’s 
going on. Others have to do with some assumptions that MacApp makes 
about the environment it’s running in. And some differences just have to do 
with THINK Pascal being a different compiler than MPW Pascal. 

Toolbox Initialization 

Since MacApp handles all of the Toolbox initialization for you, be sure that 
you turn off THINK Pascal’s automatic initialization with the { $1-} direc¬ 
tive. If you don’t, your application will crash. 

Busy cursor 

When you’re running under the environment, be sure that the qBusyCur- 
sor compiler variable is set to 0. Setting the compiler variable this way dis¬ 
ables the cursor changing code. When your program is running under the 
THINK Pascal environment, the debugging code in THINK Pascal doesn’t re¬ 
turn quickly enough to give the VBL task that manages the cursor changing 
enough time to run. 


Warning 

If you try to run your application in the THINK Pascal envi¬ 
ronment with qBusyCursor set to 1, your application will 
crash. 


The projects in the MacApp Seeds folder have qBusyCursor set correctly. 

Segmentation in MacApp 

MacApp makes several assumptions about code resources. That’s why you 
should be sure to follow Apple’s recommendations on segmenting MacApp- 
based programs. Here are some things to watch out for: 
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• The segment named Main must the be first segment in your 
project. When you look at your project by segment, this segment 
should be the one at the top of the list. 

• MacApp assumes that code segments are in the application’s re¬ 
source file. When you run in the THINK Pascal environment, 
your code segments are in the project document, not the applica¬ 
tion’s resource file. The UMemory unit in the THINK MacApp 
folder is modified to look for CODE resources in the right place. 

• Typically, you can’t have more than 32K in a segment of your ap¬ 
plication. While you’re running under the THINK Pascal environ¬ 
ment, you can have up to 64K in a code segment. When you 
build your final application, though, no segment can have more 
than 32K. 

UObject and instantiation by name 

The UObject unit that THINK Pascal uses is not the same as the UObject 
unit that comes with the MacApp package. The THINK Pascal UObject unit 
knows how THINK Pascal implements objects. 

One service that UObject provides is object instantiation by name. Some¬ 
times, the smart linker may remove references to a class that you may later 
want to instantiate by name. To make sure that THINK Pascal doesn’t re¬ 
move references to classes in this case, you can use the member function 
like this: 

procedure ForceReferences; 

begin 

if member(nil, ClassName) then 
{ null clause } ; 

end; 
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Entries in bold face refer to menu commands. Entries in typewriter 
face refer to functions, methods, variables, keywords, or files. 


Numerics 

16-bit coordinates 79, 80-81 
32-bit coordinates 79, 80-81 

A 

AbortlnQueue 46l 
AboutToPrint 

CDocument 266 
CEditText 276 
CPane 329 
CPanorama 350 
abstract classes 67 
AbTx resource 87 
Activate 72 
CControl 234 
CDesktop 244 
CDirector 252 
CEditText 272 
CFWDesktop 290 
CScrollBar 385 
CSizeBox 402 
CView 440 
CWindow 455 
activate events 72 
ActivateDirector 
CDirector 252 
CDirectorOwner 256 
ActivateWind 
CDirector 253 

Add 

CCluster 218 
AddDependent 

CCollaborator 228 
AddDirector 

CDirectorOwner 256 


AddLongPt 463 
AddMenu 

CBartender 173 
AddProvider 

CCollaborator 228 
AddSubview 
CView 445 
AddWind 

CDesktop 247 
CFWDesktop 291 
AdjustBounds 
CEditText 275 
AdjustCursor 87 
CAbstractText 130 
CDesktop 246 
CFWDesktop 291 
CView 442 
AdjustHoriz 
CPane 326 
Ad justScrollMax 
CScrollPane 390 
AdjustToEnclosure 
CPane 326 
AdjustVert 
CPane 326 
alert resources 96 
ALRT resources 96 
ancestor, See superclass 
Append 

CList 298 

Apple menu 89, 98 
AppleEventIdle 
CSwitchboard 408 
applications 

commands, handling 75 
subclass, writing your 74 
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writing 72—77 

Art Class Demo folder 12 
ASSERT macro 95 
Assert procedure 96 
AssignldleChore 
C Application 158 
AssignUrgentChore 
CApplication 158 
auto key events 72 
AutoScroll 

CPanorama 349 

B 

bartender 67, 71 
base class, See superclass 
Be comeGopher 

CAbstractText 124 
CBureaucrat 191 
BeginDrawing 
CBitMap 182 
BeginTracking 
CMouseTask 311 
bounds rectangle 84 
BringBehind 460 
BringFront 
CList 298 

BroadcastChange 
CBureaucrat 191 
CCollaborator 227 
Browser 55-60 
bureaucrats 70 

c 

CAbstractText 117 

resources, reading from 87 
CalcAperture 
CPane 331 
Ca1cBo rde rRe ct 
CPaneBorder 340 
CalcFrame 
CPane 330 
CalcTERects 
CEditText 275 
CalcTopFloat 

CFWDesktop 292 
Calibrate 

CScrollPane 390 
CanBeGopher 
CView 440 

CancelDependency 
CCollaborator 227 
CancelIdleChore 


CApplication 158 
CancelTyping 

CTextEditTask 424 
canFail 93 
CanStillType 

CTextEditTask 423 
CAppleEvent 131 
CApplication 137 

See also applications 
CArray 159 
catch handler 103 
THINK C 106 
THINK Pascal 109 
CATCH macro 106 
CatchFailure 109, 110 
CBarOwner 8 
CBartender 165 
CBitMap 179 
CBitMapPane 183 
CBorder 8 
CBureaucrat 187 
CButton 193 
CCharGrid 197 
CCheckBox 201 
CChore 205 
CClipboard 209 
CCluster 8, 217 
CCollaborator 223 

See also collaborators 
CCollection 229 
CColorWindow 8 
CControl 231 
CDataFile 8, 237 
CDecorator 241 
CDesktop 243 
CDirector 249 

See also directors 
CDirectorOwner 255 
CDocument 259 

See also documents 
CEditText 269 

resources, reading from 87 
CenterWindow 
CDecorator 242 
CenterWithinEnclosure 
CPane 327 
CEnvironment 279 
CError 281 
CFile 8, 285 
CFWDesktop 289 
CGridSelector 293 
chain of command 70 
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ChangeName 
CFile 288 

ChangeSelection 
CSelector 395 
ChangeSize 
CControl 234 
CPane 326 
CScrollPane 390 
CWindow 456 
CheckAllocation 283 
checking menu items 90 
Checklnsertion 
CEditText 273 
CheckMarkCmd 
CBartender 175 
CheckOSError 
CError 282 

CheckResource 283 
ChooseFile 

C Application 157 
Chooseltem 

CMenuDefProc 307 
CSelectorMDEF 400 
Class Browser 55-60 
class variables 

naming conventions 66 
classes 20, 27-29 
abstract 67 
declaring 27 

finding declaration 55—56 
forward references 28 
naming conventions 66 
organizing 35 
root class 28 

testing for membership in 30 
type compatibility 29 
which to define 23 
Cleanup 

CDesktop 248 
CFWDesktop 292 
clicks 71 

drawing, and 81 
receiving in pane 77 
CList 8, 297 
Clone 

CObject 314 
Close 

CClipboard 212 
CDataFile 239 
CDirector 253 
CDirectorOwner 257 
CDocument 264 


CFile 287 
CResFile 378 
CWindow 452 
ClosePrintMgr 
CPrinter 366 
CloseWind 

CClipboard 212 
CDirector 253 
CDocument 264 
CTearOffMenu 418 
CMBarChore 301 
cmdNull 88 
CMenuDefProc 303 
CMouseTask 309 
CNTL resources 97 
CObject 313 
collaborators 71 
ColorQDIsPresent 462 
Command keys, handling 72, 88 
command numbers 88 

menu resources, in 89 
negative 90 
command, chain of 70 
commands 71 

application, handling 75 
document, handling 75 
menu, handling 88 
See also events 

Compatibility clases 8 
Compatibility classes folder 11 
ConcatPStrings 46l 
ConfirmClose 

CDocument 264 
constants 

naming conventions 66 
Contains 

CDesktop 246 
CPane 324 
CView 439 
CWindow 454 

Control classes folder 11 
control resources 97 
control, flow of 71 
conventions, naming 66 
ConvertGlobal 
CClipboard 215 
converting coordinates 80—81 
ConvertPrivate 
CClipboard 215 
coordinate systems 79 
panes, and 80—81 
panoramas, and 84 
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Copy 

CObject 314 
CopyFrom 

CBitMap 182 
CopyFromTemporary 
CArray l64 
CopyPString 462 
CopyText Range 

CAbstractText 126 
CopyTo 

CBitMap 182 
CopyToTemporary 
CArray l64 
core classes 67 
Core classes folder 11 
CPane 315 

See also panes 
CPaneBorder 335 
CPaneMDEF 341 
CPanorama 345 

See also panoramas 
CPatternGrid 351 
CPictFile 355 
CPicture 357 

resources, reading from 87 
CPNTGFile 361 
CPrinter 363 
CRadioButton 8 
CRadioControl 371 
CRadioGroup 8 
CRadioGroupPane 373 
CreateDocument 74 
CApplication 157 
CreateNew 
CFile 287 
CResFile 378 
CResFile 377 
criticalBalance 92 
CRunArray 379 
CScrollBar 383 
CScrollPane 387 
CScrollPnae 

See also scroll panes 
CSelector 393 
CSelectorMDEF 399 
CSizeBox 401 
CStack 403 
CStaticText 8 
CSwitchboard 405 
CTask 411 

See also tasks 
CTearChore 415 


CTearOffMenu 417 
CTextEditTask 421 
CTextEnvirons 431 
CTextStyleTask 427 
cursor tracking 87 

See also mouse tracking 

CView 435 

See also views 
CWindow 449 

D 

data member, See instance variable 
DataSize 

CClipboard 214 
Dawdle 

CBureaucrat 190 
CEditText 276 
Deactivate 72 
CControl 234 
CDesktop 244 
CDirector 252 
CEditText 272 
CFWDesktop 290 
CScrollBar 385 
CSizeBox 402 
CView 441 
CWindow 455 
DeactivateDirector 
CDirector 252 
CDirector Owner 256 
DeactivateWind 
CDirector 253 
Debug. Settings .R 494 
DebugExceptions 96 
debugging 95-96 
THINK C aids 95 
THINK Pascal aids 96 
DeleteAll 

CRunArray 381 
DeleteFromBar 
CBartender 173 
Deleteltem 
CArray 162 
DeleteRange 

CTextEditTask 424 
DeleteRun 

CRunArray 382 
DeleteValue 

CRunArray 381 
dependents 71 
DependUpon 

CCollaborator 227 
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derived class, See subclass 
desk accessories, and THINK Class Li¬ 
brary 72 
desktop 69 

Dialog classes folder 11 
dialog resources 96 
dimALL 91 

dimming menu items 90 
dimNONE 91 
dimSOME 91 
direct commands 67 
directors 71 
DisableCmd 

CBartender 174 
DisableMenu 

CBartender 174 
DisableMenuBar 
CBartender 174 
Dispatch 

CSwitchboard 409 
DispatchClick 71 
CDesktop 245 
CView 441 
CWindow 457 
DispatchCursor 
CDesktop 246 
CView 442 
CWindow 457 
Dispose 

CAbstractText 120 
CArray l6l 
CBitMap 181 
CBitMapPane 185 
CBureaucrat 188, 358 
CCharGrid 200 
CCluster 218 
CCollaborator 226 
CControl 232 
CDesktop 244 
CDirector 251 
CDirectorOwner 256 
CDocument 262 
CEditText 271 
CFile 286 
CFWDesktop 290 
CObject 314 
CPane 323 
CPatternGrid 354 
CPictFile 356 
CPNTGFile 362 
CPrinter 366 
CSizeBox 402 


CTextEditTask 423 
CView 438 
CWindow 451 
document, for your 75 
pane, for your 77 
dispose procedure 30, 38 
DisposeAll 
CCluster 218 
Disposeltems 
CCluster 218 
DITL resources 96 
Do 

CTask 413 
CTextEditTask 423 
CTextStyleTask 428 
DoActivate 

CSwitchboard 407 
DoAppleEvent 

CApplication 151 
CBureaucrat 190 
DoAutoKey 72 

CAbstractText 123 
CApplication 148 
CBureaucrat 189 
DoBackspace 

CTextEditTask 424 
DoClick 71 

CControl 235 
CEditText 271 
CScrollBar 385 
CSelector 395 
CView 441 
pane, for your 77, 81 
DoCommand 

application, for your 75 
CAbstractText 122 
CApplication 149 
CBureaucrat 189 
CDirector 251 
CDocument 263 
document, for your 75 
menus, for your 88, 90 
documents 74, 75—76 

commands, handling 75 
subclass, writing your 75 
See also files 
DoDeactivate 

CSwitchboard 407 
DoDiskEvent 

CSwitchboard 406 
DoDoubleClick 
CSelector 397 
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DoForEach 

CCluster 220 
DoForEachl 
CCluster 221 
DoFwdDelete 

CTextEditTask 424 
DoGoodClick 

CButton 195 
CCheckBox 203 
CControl 236 
CRadioControl 372 
DoHighLevelEvent 
CSwitchboard 408 
DoHorizScroll 
CScrollPane 390 
Doldle 

CSwitchboard 407 
DoKeyDown 72 

CAbstractText 123 
CApplication 148 
CBureaucrat 189 
CPanorama 350 
DoKeyEvent 

CSwitchboard 406 
DoKeyUp 

CApplication 149 
CBureaucrat 189 
DoMouseDown 

CSwitchboard 406 
DoMouseUp 

CDesktop 246 
CSwitchboard 406 
CView 441 
DonePrinting 
CDocument 266 
CEditText 276 
CPane 329 
CPanorama 350 
DoNormalChar 

CTextEditTask 424 
DoOt he rEvent 

CSwitchboard 407 
DoPageSetup 
CPrinter 368 
DoPrint 

CPrinter 368 
DoResume 

CSwitchboard 407 
DoRevert 76 

CDocument 266 
DoSave 76 

CDocument 2 66 


DoSaveAs 

CDocument 266 
DoSaveFileAs 

CDocument 267 
DoScroll 

CScrollPane 391 
DoSuspend 

CSwitchboard 407 
DoTask 

CTask 413 
CTextEditTask 423 
CTextStyleTask 428 
DoThumbDrag 

CScrollPane 391 
DoThumbDragged 
CControl 235 
CScrollBar 385 
DoTyping 

CTextEditTask 423 
DoUpdate 

CSwitchboard 407 
DoVertScroll 
CScrollPane 391 
Down Arrow key 59 
Drag 

CWindow 455 
DragWind 

CDesktop 247 
CFWDesktop 292 
Draw 80 

CBitMapPane 185 
CControl 234 
CEditText 271 
CGridSelector 294 
CPane 328 
CPicture 359 
CScrollBar 385 
CSizeBox 402 
DrawAll 

CControl 234 
CPane 328 
DrawBorder 

CPaneBorder 339 
DrawGrid 

CGridSelector 295 
drawing, in pane 80 
Drawltem 

CCharGrid 200 
CGridSelector 295 
CPatternGrid 354 
DrawMenu 

CMenuDefProc 307 
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CPaneMDEF 342 
DrawSICN459 

E 

Edit menu 89, 98 
Empt yG1oba1S c rap 
CClipboard 215 
EmptyLongRect 465 
EmptyScrap 

CClipboard 2l6 
EnableCmd 

CBar tender 174 
EnableMenu 

CBartender 174 
EnableMenuBa r 
CBartender 174 
encapsulation 19 
enclosures 69, 77 
EnclosureScrolled 
CPane 327 
EnclToFrame 
CPane 332 
EnclToFrameR 
CPane 332 
EndDrawing 
CBitMap 182 
EndTracking 94 
CMouseTask 311 
ENDTRY macro 106 
Enter key 59 
EqualLongPt 463 
EqualLongRect 465 
EqualMem 468 

error handling, See exception handling 
error messages 

displaying your own 106 , 115 
exception handling, and 105 
strings, for THINK Class Library 97 
error parameter 110 
ErrorAlert 466 
Estr resources 97 
events 

passing to objects 71 
See also commands 
exception handling 103—116 

error messages, displaying 105, 115 
Exit, and 113 
memory allocation 105 
objects, creating 105, 107, 111 
propagating errors 109, 113 
retrying try handler 109, 113 
returning values 108 


THINK C 106-109 
THINK Pascal 109-113 
Exceptions.h 106 
ExistsOnDisk 
CFile 287 
Exit 

CApplication 156 

Exit, and exception handling 113 
ExitApp 

CApplication 156 
ExtractFromDescList 
CAppleEvent 134 

F 

Faillnfo 110 
FailMemError 115 
FailNIL 105 , 115 
FailNILRes 115 
FailOSErr 115 
FailResError 115 
Failure 114 
fi variable 110 
File classes folder 11 
File menu 89, 98 
files 

documents, and 71 
See also documents 
FindCmdNumber 88, 90 
CBartender 175 
FindDlogPosition 460 
Findlndex 
CList 299 
Findltem 

CCluster 219 
CGridSelector 295 
CSelector 396 
Findlteml 

CCluster 219 
FindltemBox 

CGridSelector 296 
FindltemText 
CBartender 176 
FindLine 

CAbstractText 130 
CEditText 276 
FindMenuIndex 
CBartender 176 
FindMenuItem 
CBartender 176 
FindRun 

CRunArray 382 
FindSubview 
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CView 446 
FindSum 

CRunArray 381 
FindViewBylD 
CDirector 251 
CView 446 

Firstltem 

CList 299 

FirstSuccess 

CList 299 

FirstSuccessl 

CList 299 

FitToEnclFrame 
CPane 327 
FitToEnclosure 
CPane 327 

flags • ^ 
naming conventions oo 

flow of control 71 

Font menu 89, 98 

ForceClassReferences 

C Application 147 

Fo rceNextP repa re 

CView 447 
ForgetHandle 468 
ForgetObject 468 
ForgetPtr 468 
ForgetResource 468 
frame coordinates 79 
frames 80 
FrameToBounds 
CPicture 360 
FrameToEncl 
CPane 332 
FrameToEnclR 
CPane 332 
FrameToGloba1R 

CPane 333 
CView 447 
CWindow 457 
FrameToQD 80 
CPane 333 
FrameToQDR 80 
CPane 333 

FrameToWind 
CPane 332 
FrameToWindR 
CPane 332 
Free 

CAbstractText 120 
CArray l6l 
CBitMap 181 


CBitMapPane 185 
CBureaucrat 188, 358 
CCharGrid 200 
CCluster 218 
CCollaborator 226 
CControl 232 
CDesktop 244 
CDirector 251 
CDirectorOwner 256 
CDocument 262 
CEditText 271 
CFile 286 
CFWDesktop 290 
CObject 314 
CPane 323 
CPatternGrid 354 
CPictFile 356 
CPNTGFile 362 
CPrinter 366 
CSizeBox 402 
CTextEditTask 423 
CView 438 
CWindow 451 
document, for your 75 
pane, for your 77 
function member, See method 
FW/Tearoffs folder 11 

G 

gApplication 473 
gAskFailure 95 
gBartender 473 
gBreakFailure 95 
gClicks 475 
gClipboard 474 
gDecorator 474 
gDesktop 473 
GenericMDEF 308 
gError 474 
Get1Height 

CAbstractText 128 
GetAEEvent 

CAppleEvent 133 
GetAERefCon 

CAppleEvent 134 
GetAEReply 

CAppleEvent 134 
GetAlignCmd 

CAbstractText 128 
CEditText 274 
GetAnEvent 

CSwitchboard 409 
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GetAperture 
CDesktop 248 
CPane 324 
CView 439 
CWindow 453 

GetBalloonlnfo 

CView 445 

GetBitMap 

CBitMapPane 185 
GetBorder 
CPane 325 
GetBorderFlags 
CPaneBorder 338 
GetBounds 

CBitMap 181 
CDesktop 248 
CPanorama 348 
GetBoundsOrigin 
CBitMap 181 
GetCharAfter 

CAbstractText 126 
GetCharBefore 

CAbstractText 126 
GetCha rOf f set 

CAbstractText 128 
CEditText 274 
GetCha rPoint 

CAbstractText 129 
CEditText 275 
GetCharStyle 

CAbstractText 129 
CEditText 275 
GetClassName 
CObject 314 
GetClickCmd 
CButton 195 
GetCmdText 

CBartender 175 

GetCommandBa se 
CSelector 396 
GetData 

CClipboard 215 
GetDescList 

CAppleEvent 134 
GetErrorResuit 
CAppleEvent 135 
GetEventClas s 

CAppleEvent 133 
GetEventID 

CAppleEvent 133 
GetExtent 

CPanorama 347 


GetFontNumber 46l 
GetFrame 
CPane 323 
CView 439 
CWindow 452 
GetFramePosition 
CPanorama 347 
GetFrameSpan 
CPanorama 347 
GetFSSpec 
CFile 287 

GetGlobalScrap 
CClipboard 213 
GetHeight 

CAbstractText 128 
CEditText 274 
GetHelpResID 
CPane 325 
CView 445 
CWindow 454 
GetHomePosition 
CPanorama 349 
Get ID 

CView 440 

GetInterior 

CScrollPane 390 
CView 439 
CWindow 452 
GetItem 

CArray l62 
GetLength 

CAbstractText 130 
CDataFile 238 
CEditText 276 
CPane 324 
GetMacPicture 
CPicture 359 
GetMacPort 
CView 439 
GetMacWindow 

CTearOffMenu 419 
GetMargin 

CPaneBorder 339 
GetMargins 

CTearOffMenu 419 
GetMark 

CDataFile 239 
GetMaxValue 
CControl 232 
GetMinValue 
CControl 232 
GetName 
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CDocument 267 
CFile 287 
GetNamelndex 
CTask 412 
GetNumltems 

CCollection 229 
CRunArray 380 
GetNumLines 

CAbstractText 130 
CEditText 276 
GetOrigin 
CPane 324 
CView 439 
GetPageArea 
CPrinter 368 
GetPagelnfo 
CPrinter 368 
GetPageStart 
CPrinter 368 
GetPattern 

CPaneBorder 338 
CPatternGrid 354 
GetPenSize 

CPaneBorder 338 

GetPhase 

C Application 148 
GetPixelExtent 
CPane 324 
CPanorama 349 
GetPosition 

CPanorama 348 
GetP rintRecord 
CPrinter 368 
GetRounding 

CPaneBorder 339 
GetScaled 

CPicture 359 
GetScales 

CPanorama 348 
GetSelection 

CAbstractText 125 
CEditText 272 
CSelector 396 
GetShadow 

CPaneBorder 339 
GetSpacingCmd 

CAbstractText 128 
CEditText 274 
GetSpecification 
CAbstractText 121 
GetStationID 

CRadioGroupPane 375 


GetSteps 

CScrollPane 390 
GetStripCount 
CPrinter 367 
GetSupervisor 
CBureaucrat 188 
GetTEFontInfo 
CEditText 274 
GetTextHandle 

CAbstractText 125 
CEditText 272 
GetTextlnfo 

CTextEnvirons 433 
GetTextRange 
CEditText 273 
GetTextStyle 

CAbstractText 129 
CEditText 275 
GetTitle 

CControl 233 
CWindow 453 
GetTopWindow 
CDesktop 248 
GetValue 

CControl 232 
CRunArray 381 
GetWantsClicks 
CView 439 
GetWCount 

CDecorator 242 

GetWholeLines 

CAbstractText 129 
Get Window 

CDirector 251 
CPane 325 

GetXferMode 
CBitMap 181 
gGopher 474 
gIBeamCursor 475 
glnBackground 477 
gLastError 477 
gLastMessage 477 
gLastMouseDown 474 
gLastMouseUp 474 
gLastViewHit 474 
global coordinates 79 
global variables 

naming conventions 66 
gopher 70, 71 
GotRequiredParams 
CAppleEvent 134 
grow icon 98 


508 Object-Oriented Programming 





- ♦ 

GrowMemory 92 

CBitMapPane 184 


CApplication 153 

IBureaucrat 


GrowZoneFunc 282 

CBureaucrat 188 


gSignature 477 

IButton 


gSleepTime 476 

CButton 194 


gSystem 475 

ICharGrid 


gUtilRgn 477 

CCharGrid 199 


gWatchCursor 475 

ICheckBox 


H 

HandleFailure 110 

CCheckBox 202 

IClipboard 

CClipboard 211 


HasResFork 

ICluster 


CResFile 378 

CCluster 218 


HavePagination 

ICollaborator 


CPrinter 366 

CCollaborator 226 


Hide 

ICollection 


CControl 233 

CCollection 229 


CDesktop 244 

icon, small, resource 98 


CFWDesktop 290 

IDataFile 


CPane 326 

CDataFile 238 


CView 440 

IDecorator 


CWindow 454 

CDecorator 242 


HideSuspend 

IDesktop 


CWindow 455 

CDesktop 244 


HideWind 

IDirector 


CDesktop 247 

CDirector 250 


CFWDesktop 291 

IDirectorOwner 


Hiliteltem 

CDirectorOwner 256 


CGridSelector 295 

Idle 


CPatternGrid 354 

CApplication 156 


CSelector 396 

IDocument 75 


HitSamePart 

CDocument 262 


CDesktop 247 

IEditText 


CSelector 395 

CEditText 270 


CView 441 

IFile 


horizontal sizing characteristics, of pane 

CFile 286 


82 

IFWDesktop 


i 

IAbstractText 

CFWDesktop 290 
IGridSelector 

CGridSelector 294 


CAbstractText 119 

IList 


IAppleEvent 

CList 297 


CAppleEvent 133 

IMenuDefProc 


IApplication 74, 92 

CMenuDefProc 307 


CApplication 142 

IMouseTask 


IArray 

CMouseTask 311 


CArray l6l 

Includes 


IBartender 

CCluster 219 


CBartender 173 

inCriticalOperation 92 


IBitMap 

INewButton 


CBitMap 181 

CButton 194 


IBitMapPane 

INewCheckBox 
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CCheckBox 202 
INewRadioControl 
CRadioControl 372 
INewWindow 

CWindow 451 
inherited keyword 32 
InitMemory 

C Application 143 
InitToolbox 

CApplication 143 
InsertAfter 
CList 298 
InsertAt 
CList 298 
InsertAtIndex 
CArray l62 
InsertHierMenu 
CBartender 174 
InsertlnBar 

CBartender 173 
InsertMenuCmd 
CBartender 175 
InsertRun 

CRunArray 382 
InsertTextHandle 
CAbstractText 126 
InsertTextPtr 

CAbstractText 126 
CEditText 273 
InsertValue 

CRunArray 380 
InsetLongRect 464 
InspectSystem 
CApplication 146 
InstallPanorama 86 
CScrollPane 389 
InstallPatches 
CApplication 147 
instance 20 
instance variables 20 
accessing 30 
declaring 28 
naming conventions 66 
referring to 30 
taking address of 36 
using in Toolbox calls 36 
instances 

See also objects 
instantiation by name 497 
instantiation, See creating 
integer type 66 
IPane 76 


CPane 321 
IPaneBorder 

CPaneBorder 338 
IPaneMDEF 

CPaneMDEF 342 
IPanorama 

CPanorama 346 
IPatternGrid 

CPatternGrid 353 
IPictFile 

CPictFile 355 
IPicture 

CPicture 358 

IPNTGFile 

CPNTGFile 361 
IPrinter 

CPrinter 365 
IRadioControl 

CRadioControl 372 
IRadioGroupPane 

CRadioGroupPane 374 

IResFile 

CResFile 377 
IResPaneBorder 
CPaneBorder 338 
IRunArray 

CRunArray 380 
IsActive 

CDirector 254 
CView 438 
IsCancelEvent 46l 
IsChecked 

CCheckBox 203 
IsColor 

CWindow 453 
IScrollBar 

CScrollBar 384 
IScrollPane 

CScrollPane 388 
IsDialogWindow 460 
ISelector 

CSelector 394 

ISelectorMDEF 

CSelectorMDEF 399 
IsEmpty 

CCollection 230 
IsFloating 

CWindow 453 
ISizeBox 

CSizeBox 401 
IsModal 

CWindow 453 
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IsMyWindow 460 
IsOpen 

CResFile 378 
IsSystemWindow 460 
IStack 

CStack 403 

IsUndone 
CTask 412 
IsVisible 
CView 438 
ISwitchboard 

CSwitchboard 406 
ITask 

CTask 412 

ITearChore 

CTearChore 415 
ITearOffMenu 

CTearOffMenu 418 
item number 90 
ItemOffset 
CArray l64 
ITextEditTask 

CTextEditTask 422 
CTextStyieTask 428 
ITextEnvirons 

CTextEnvirons 433 
IView 

CView 437 
IViewRes 87 

CAbstractText 120 
CEditText 270 
CPane 323 
CPanorama 347 
CPicture 358 
CScrollPane 389 
CView 438 
IViewTemp 

CPane 323 
CPanorama 347 
CPicture 358 
CScrollPane 389 
CView 438 
IWindow 

CWindow 450 

J 


key down events 72 
KeylsDown 46l 
keywords 37 
kSilentError 106 

L 

Lastltem 

CList 299 
LastSuccess 

CList 300 
LastSuccessl 

CList 300 
LClipRect 471 
LCopyBits 471 
Left Arrow key 59 
LEraseOval 469 
LEraseRect 469 
LEraseRoundRect 470 
LFillOval 470 
LFillRect 469 
LFillRoundRect 471 
LFrameOval 470 
LFrameRect 469 
LFrameRoundRect 470 
LInvertOval 470 
LInvertRect 469 
LInvertRoundRect 470 
LLineTo 471 
LMoveTo 471 
local coordinates 79 
location, of pane 77 
Lock 

CObject 314 

long coordinates 79, 80-81 
long int type 66 
longint type 66 
LongPt 80 
LongRect 80 
LongToQDPt 463 
LongToQDRect 464 
LPaintOval 470 
LPaintRect 469 
LPaintRoundRect 470 
LRectRgn 471 

M 


JumpToEventLoop 
CApplication 157 

K 

KeepTracking 94 
CMouseTask 311 


MacApp 

busy cursor 496 
compiler variables 492 
converting 486 
environment differences 496 
minimum requirements 484 
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resource files 494 
seed projects 490 
segmentation 496 
Toolbox initialization 496 
MacApp Seeds folder 490 
MacApp .71 490 
MacApp. Bui Id. 71 490 
MacApp.Build.Debug .n 490 
MacApp. Debug. 71 490 
MacApp.Debug.Rsrc 495 
MacApp .rsrc 495 
MacApp. Script 486 
MakeBartender 
CApplication 146 
MakeClipboard 
CApplication 144 
MakeClipView 
CClipboard 2l6 
MakeCurrent 
CResFile 378 
MakeDecorator 
CApplication 145 
MakeDesktop 

CApplication 144 
MakeEditTask 

CAbstractText 124 
MakeError 

CApplication 144 
MakeMacTE 

CEditText 271 
MakeMacWindow 
CWindow 452 
MakePrinter 

CDocument 265 
MakeStyleTask 

CAbstractText 124 
MakeSwitchboard 
CApplication 144 
MatchView 
CView 446 
MBAR resource 98 
member 20 

member function 30, 38 
member function, See method 
members 

See also instance variables, methods 
memory 

allocation and exception handling 

105, 115 

memory allocating 

document, for your 75 
memory, allocating 92 


pane, for 77 
MemoryReplenished 
CApplication 154 
MemoryShortage 92 
CApplication 153 
menu bar resource 98 
menu ID 90 
MENU resources 89, 97 
MENUapple 89 
MENUedit 89 
MENUfile 89 
MENUfont 89 
menus 88-92 

adding items 90 
checking items 90 
clicking in 90 
creating in code 90 
dimming items 90 
resources, reading from 89 
MenuSelect 91 
MENUsize 89 
message parameter 110 
messages 19 
sending 32 
See also methods 
methods 20, 31—32 
calling 32 
calling inherited 32 
declaring 28 
defining 31 

Finding definition 57—59 
monomorphic 32 
overriding 28 

referring to current object 31 
«%_MethTables» 95 
«%_MethTables» 35 
Mi s sin gRe sources 
CError 282 

monomorphic methods 32 
More classes folder 11 
MoreSlots 
CArray l64 

mouse clicks, See clicks 
mouse tracking 94 

See also cursor tracking 
Move 

CWindow 456 
MoveDown 
CList 298 

MoveltemToIndex 
CArray l63 
MoveOffScreen 
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CWindow 456 
MoveToCorner 

CTearOffMenu 419 
MoveToIndex 
CList 299 
MoveUp 

CList 298 

MultiFinder, running under 72 

N 

naming conventions 66 
new operator 

exception handling, and 105 
new procedure 30, 37 
New, handling 74, 76 
NewClassDemo Folder 12 
NewFile 76 

CDocument 264 
NewHandleCanFail466 
NIL 66 

N0_PR0PAGATE macro 109 
Notify 93, 94 

C Application 148 
CBureaucrat 189 
CDocument 262 
Nthltem 

CList 299 
NULL 66 

o 

object reference 29 
objects 19, 29—30 

as handles 29, 35 
creating 30 

creating and exception handling 
105, 107, 111 
defining 29 
deleting 30 

in desk accessories and code re¬ 
sources 27 
segmentation 35 
self 31 
size of 37 

type compatibility 29 
OCluster 8 
ODataFile 8 
Offset 

CCluster 219 
CControl 234 
CPane 326 

Of f setLongRect 464 
OFile 8 


OList 8 
Open 

CDataFile 239 
CFile 287 
CResFile 378 
Open..., handling 74, 76 
OpenDocument 74 
CApplication 157 
OpenFile 76 

CDocument 265 
OpenPrintMgr 
CPrinter 366 
origin 84 
OutOfMemory 

CApplication 154 
override keyword 28 
overriding methods 21 
OwnsWindow 

CDirector 251 

P 

PackageAppleEvent 
CApplication 150 
PageCount 

CDocument 265 
PageNumToStrips 
CPrinter 368 
Paginate 

CAbstractText 125 
CDocument 265 
CPane 329 
CPanorama 350 
Pane resource 87 
panes 77—87 

clicks, receiving 77 
coordinates 79, 80-81 
drawing 80 
initializing 76 
location, setting 77, 81—83 
memory, allocating 77 
moving 81 
resizing 81 

resources, reading from 87 
scrolling 83—86 
subclass, writing your 76 
supervisor, and 77 
windows, and 78 
See also windows 
Pano resource 87 
panoramas 83—86 

resources, reading from 87 
parameters 
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naming conventions 66 
PctP resource 87 
Perform 

CChore 206 
CMBarChore 301 
CTearChore 415 
PerformEditCommand 
CAbstractText 123 
CEditText 271 
PickFileName 

CDocument 267 
PinlnRect 460 
PixellsBlack 
CBitMap 181 
Place 

CPane 326 
PlaceNewWindow 
CDecorator 242 
PlacePopUp 

CMenuDefProc 307 
polymorphism 22 
Pop 

CStack 403 
position 84 

PositionDialog 46l 
PostAlert 
CError 282 
Preload 

CApplication 155 
Prepare 79 

CControl 234 
CDesktop 248 
CPane 330 
CView 447 
CWindow 456 
PrepareToPrint 
CPane 330 
Prepend 
CList 298 
PrintPage 

CEditText 276 
CPane 329 
CPanorama 350 
PrintPageOfDoc 
CDocument 266 
PrintPageRange 
CPrinter 369 
PrivateChanged 
CClipboard 2l6 
ProcesslEvent 
CApplication 155 
ProcessEvent 


CSwitchboard 408 
ProviderChanged 
CBureaucrat 191 
CCollaborator 227 
CDirector 254 
CRadioGroupPane 375 
providers 71 
Pt2LongRect 465 
PtlnLongRect 465 
PtlnQDSpace 464 
PtInTearRgn 

CPaneMDEF 344 
Push 

CStack 403 

PushTryHandler 114 
PutData 

CClipboard 214 
PutGlobalScrap 
CClipboard 213 

Q 

qBusyCursor 496 
QDToFrame 
CPane 333 
QDToFrameR 
CPane 333 
QDToLongPt 463 
QDToLongRect 464 
QuickDraw coordinates 79, 80—81 
Quit 

CApplication 156 
CDirectorOwner 257 
Quit, handling 75 

R 

rainy day fund 92 

raising exceptions, See exception han¬ 
dling 
ReadAll 

CDataFile 239 
CPictFile 356 
ReadNewBitMap 
CPNTGFile 362 
ReadSome 

CDataFile 240 
ReallyVisible 

CDesktop 245 
CPane 324 
CView 438 

RectlnQDSpace 465 
Redo 

CTask 413 
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CTextEditTask 423 
Refresh 80 
CPane 328 
RefreshBorder 
CPane 329 
RefreshLongRect 
CPane 329 

RefreshRect 
CPane 328 
Remove 

CCluster 219 
RemoveDependent 
CCollaborator 228 
RemoveDirector 

CDirectorOwner 256 
RemoveMenu 

CBar tender 173 
RemoveMenu Cmd 
CBartender 175 
RemovePatche s 
CApplication 147 
RemoveProvider 
CCollaborator 228 
RemoveSubview 
CView 446 
RemoveWind 

CDesktop 247 
CFWDesktop 291 
RequestInteraction 
CAppleEvent 134 
RequestMemory 
CApplication 151 
ResEdit 13 
ResetPagination 
CPrinter 366 
Resize 

CArray l64 
CWindow 456 
ResizeFrame 

CAbstractText 130 
CEditText 275 
CPane 330 
CPanorama 349 
CPicture 359 

ResizeHandleCanFail466 
ResolveFileAlias 
CFile 287 
resource files 

for MacApp 494 
menus, reading from 89 
THINK Class Library, for 72, 96-99 
views, reading from 87 


Restore 

CEnvironment 279 
CTextEnvirons 433 
RestoreEnvironment 
CPane 330 

RestoreQuickDraw 
CPaneMDEF 344 
RestoreRange 

CTextEditTask 425 
RestoreStyle 

CTextStyleTask 429 
Resume 

CApplication 155 
CClipboard 212 
CDirector 253 
CDirectorOwner 257 
CTearOffMenu 418 
resume events 72 
ResumeAfterError 96 
Retrieve 

CArray 163 
RETRY macro 109 
RetryException 114 
retrying try handler 109, 113 
Return key 59 

returning values and exception handling 
108 

Revert, handling 76 
Right Arrow key 59 
root class 21, 28 
. rsrc file, See resource file 
Run 

CApplication 154 

s 

•Samples From MacApp 493 
Save, handling 76 
SaveRange 

CTextEditTask 424 
SaveStyle 

CTextStyleTask 429 
SBarActionProc391 
SBa rThumbFun c391 
scale 84 

ScPn resource 87 
Sc rapConve rted 
CClipboard 214 
Scroll 

CEditText 272 
CPanorama 349 
scroll panes 86 
scrolling 83^86 
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ScrollTo 

CPanorama 349 
ScrollToSelection 
CAbstractText 124 
CPanorama 349 
Search 

CArray 163 
Se ctApe rtu re 
CPane 333 
SectLongRect 464 
seed projects 490 
segmentation 35, 94 
MacApp 496 
Select 

CWindow 455 
SelectAll 

CAbstractText 125 
SelectionChanged 
CAbstractText 124 
CTextEditTask 424 
SelectWind 

CDesktop 247 
CFWDesktop 291 
self (current object) 31 
«%_SelProcs. 95 
«%_SelProcs» 35 
SendBack 
CList 298 
SetActClick 
CWindow 453 
Set Act ionP roc 
CControl 233 
SetAlignCmd 

CAbstractText 127 
CEditText 274 
SetAlignment 
CEditText 274 
Set Allocation 93, 466 
SetAllStripHeights 
CPrinter 367 
SetAllStripWidths 
CPrinter 367 
SetBitMap 

CBitMapPane 185 
SetBlockSize 
CArray l6l 
SetBorder 
CPane 325 
SetBorderFlags 
CPaneBorder 338 
SetBounds 

CPanorama 347 


SetCanBeGopher 
CView 440 
SetClickCmd 
CButton 195 
SetCmdText 

CBartender 175 
SetCommandBase 
CSelector 396 

SetCriticalOperation 93, 467 
CApplication 152 
SetCursor 87 
SetDefault 
CButton 195 
SetDimOption 91 
CBartender 176 
SetErrorResult 
CAppleEvent 135 
SetFaillnfo 116 
SetFontName 

CAbstractText 127 
SetFontNumbe r 

CAbstractText 127 
CEditText 273 
SetFontSize 

CAbstractText 127 
CEditText 273 
SetFontStyle 

CAbstractText 127 
CEditText 273 
SetFrameOrigin 
CPane 323 
SetGridOn 

CGridSelector 296 
SetHelpResID 
CWindow 454 
SetHorizPageBreak 
CPrinter 367 
Set ID 

CView 440 

SetItem 

CArray 162 
SetLength 

CDataFile 238 
SetLockChanges 
CArray l6l 
SetLongPt 463 
SetLongRect 464 
SetMacPicture 
CPicture 359 

SetMargin 

CPaneBorder 339 
SetMargins 
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CTearOffMenu 419 
SetMark 

CDataFile 238 
SetMaxValue 
CControl 232 
SetMinimumStack 468 
SetMinValue 
CControl 232 
SetModal 

CWindow 453 
SetOverlaps 

CScrollPane 390 
SetPattern 

CPaneBorder 338 
SetPenSize 

CPaneBorder 338 
SetPosition 

CPanorama 348 
SetPrintClip 
CPane 325 
SetPrintDir 
CPrinter 366 
SetResBorder 
CPane 325 
SetRounding 

CPaneBorder 339 
SetScaled 

CPicture 359 
SetScales 

CPanorama 348 
SetScrollPane 
CPanorama 348 
SetSelection 

CAbstractText 124 
CEditText 272 
SetShadow 

CPaneBorder 339 
SetSizeRect 
CWindow 454 
SetSpacingCmd 

CAbstractText 128 
CEditText 274 
SetStationID 

CRadioGroupPane 375 
SetStdState 
CWindow 454 
SetSteps 

CScrollPane 389 
SetStripHeight 
CPrinter 367 
SetStrips 

CPrinter 366 


SetStripWidth 
CPrinter 367 
SetTextHandle 

CAbstractText 125 
SetTextlnfo 

CTextEnvirons 433 
SetTextMode 

CAbstractText 127 
CEditText 273 
SetTextPtr 

CAbstractText 125 
CEditText 272 
SetTextString 

CAbstractText 125 
SetThumbFunc 
CScrollBar 384 
Settings .R 494 
SetTitle 

CControl 233 
CWindow 453 
SetUnchecking 91 
CBartender 177 
SetUpFileParameters 74 
C Application 145 
SetUpMenus 89 

CApplication 146 
SetupQuickDraw 
CPaneMDEF 344 
SetValue 

CControl 232 
CRunArray 381 
SetVertPageBreak 
CPrinter 367 
SetWantsClicks 

CView 439 

SetWholeLines 

CAbstractText 129 
SetXferMode 
CBitMap 181 
SevereMacE rror 
CError 282 
SFSpecify 
CFile 286 

short coordinates 79, 80-81 
short int type 6o 
Show 

CControl 234 
CDesktop 244 
CFWDesktop 290 
CPane 325 
CView 440 
CWindow 454 
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ShowOrHide 

CWindow 455 
ShowResume 

CWindow 455 
ShowWind 

CDesktop 247 
CFWDesktop 291 
SICN resource 98 
Simulated ick 
CButton 195 

16-bit coordinates 79, 80-81 
Size menu 89, 98 
sizELASTIC 82 
SizeMenu 

CMenuDefProc 307 
CPaneMDEF 343 
sizFIXEDBOTTOM 82 
sizFIXEDLEFT 82 
sizFIXEDRIGHT82 
sizFIXEDSTICKY 82 
sizFIXEDTOP 82 
sizing characteristics, of pane 81—83 
small icon resource 98 
Specify 

CAbstractText 120 
CFile 286 
SpecifyFSSpec 
CFile 286 
SpecifyHFS 
CFile 286 
SpecifyMsg 115 
StaggerWindow 
CDecorator 242 
Starter Folder 12 
Starter project 
building 12 

writing program with 72—77 
StartUpAction 
CApplication 155 

static data member, See class variable 
static member function, See class method 
Status 

CClipboard 214 
Store 

CArray l62 
StoreToClip 

CTextEditTask 425 
STR resources 98 
STR# resources 99 
string resources 98 
strings, error messages 97 
subclass 21 


when to create 23 
See also class 

SubclassResponsibility 
CObject 314 
SubLongPt 463 
SubpaneLocation 
CView 446 
Success 110, 113 
SumRange 

CRunArray 381 
superclass 21 
supervisors 70 
panes, and 77 
Suspend 72 

CApplication 155 
CClipboard 212 
CDirector 252 
CDirectorOwner 256 
CTearOffMenu 418 
suspend events 72 
Swap 

CArray 163 
switchboard 67, 71 
SwitchFromDA 

CApplication 156 
SwitchToDA 

CApplication 156 

T 

Tab key 59 

Table classes folder 11 
tasks 93 

TCL 1.1 doc folder 12 

TCL 1.1 Pascal Demos folder 12 

TCL 1.1 Pascal Demos.sea 12 

_TCL_DEBUG_95 

TCL Libraries folder 11 
TCL Resources 72 
TCL Resources folder 12 
TCL TMPLs 87 
installing 13 
TCL TMPLs folder 12 
TCL_DEBUG 96 
TCLRuntime.lib 

exception handling, and 105 
TearOffMenu 

CPaneMDEF 343 
TempMemCalIsAvailable 462 
Text classes folder 11 
THINK Class Library 65-100 
chain of command 70 
class diagram 67 


5 1 8 Object- Orien ted Programming 



distributing 100 
flow of control 71 
modifying 99 
naming conventions 66 
resources 96—99 
seed projects 12 
visual hierarchy 69 

THINK Class Library 1.1 folder 11 
THINK Class Library 1.1.sea 11 
32-bit coordinates 79, 80-81 
ThrowOut 
CFile 288 

TinyEdit Folder folder 12 
TMPL resources 13 
TObject 35-35 
Toggle 

CClipboard 212 
Toolbox routines 

exception handling, and 115 
pane coordinates for 79 
toolboxBalance 92 
TornOff 

CTearOffMenu 419 
tracking, cursor 87 
tracking, mouse 94 
TrackMouse 
CView 331 

TrapAvailable 462 
try handler 103 

retrying 109, 113 
THINK C 106 
THINK Pascal 109 
TRY macro 106 
Type 

CEditText 271 

type 

C and Pascal 65 
TypeChar 

CAbstractText 123 
typing, handling 72 

u 

UMemory 497 
Undo 93, 94 
CTask 413 
CTextEditTask 423 
CTextStyleTask 428 
undo 93 

UnionLongRect 465 
units, panorama 84 
UObject 497 
Up Arrow key 59 


Update 72 

CResFile 378 
CWindow 456 
update events 72, 80 
UpdateAllMenus 
CBartender 177 
UpdateDisplay 
CClipboard 213 
UpdateMenuBar 
CBartender 177 
UpdateMenus 90 

CAbstractText 122 
CApplication 150 
CBureaucrat 190 
CDirector 252 
CDocument 263 
UpdateUndo 

CDocument 267 
UpdateWindows 
CDesktop 247 
UseLongCoordinates 
CView 440 
UsePICT 

CPicture 359 

V 

variables 

naming conventions 66 
vertical sizing characters, of pane 82 
View resorce 87 
views 69 

resources, reading from 87 
visual hierarchy 69 
visual messages 67 

w 

WantsActClick 

CWindow 453 
WIND resources 99 
window coordinates 79 
window resources 99 
windows 

documents, and 71 
events, handling 71, 72 
panes, and 78 
See also panes 
WindToFrame 
CPane 331 
WindToFrameR 
CPane 332 

WNEIsImplemented 462 
WriteAll 
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CDataFile 240 
CPictFile 356 
WriteBitMap 

CPNTGFile 362 
WriteSome 

CDataFile 240 

z 

Zoom 

CWindow 456 
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